Multilead Open API MCP Server

多引线开放式API MCP服务器

一个全面的FastMCP服务器，提供对 多引线开放式API 拥有74个端点，用于潜在客户管理、活动、对话、网络钩子和分析。

概述

此MCP服务器使Claude和其他AI助手能够与Multilead平台进行交互，以：

• 潜在客户管理（32个端点）：使用自定义字段和标签创建、检索、更新、删除、搜索和丰富潜在客户
• 活动管理（12个端点）：设计、执行和监控具有高级定位功能的电子邮件活动
• 对话（15个端点）：访问电子邮件线程、消息历史记录和对话分析
• Webhooks（8个端点）：为潜在客户、活动和对话设置实时事件通知
• 分析和报告（7个端点）：生成绩效报告、跟踪指标和分析趋势

特性

• 完全异步/等待支持高性能操作
• 全面的错误处理，并提供有用的错误消息
• 通过承载令牌（API密钥）进行身份验证
• 速率限制和重试逻辑
• 使用Pydantic模型进行类型安全操作
• 包括示例工具、资源和提示
• 用于添加所有74个API端点的生产就绪结构

先决条件

• Python 3.10或更高版本
• 包管理器: uv （推荐）或 pip
• 多线索API密钥：请在 https://app.multilead.co/settings/api

安装

1.克隆或导航到项目

cd /home/gotime2022/Projects/mcp-servers/multilead-mcp

2.创建虚拟环境

使用紫外线（推荐）：

uv venv
source .venv/bin/activate  # On Linux/Mac
# or
.venv\Scripts\activate  # On Windows

使用标准venv：

python -m venv .venv
source .venv/bin/activate  # On Linux/Mac
# or
.venv\Scripts\activate  # On Windows

3.安装依赖项

使用紫外线：

uv pip install -e .

使用pip：

pip install -e .

4.配置环境变量

复制示例环境文件并添加您的API密钥：

cp .env.example .env

编辑 .env 并替换 your_multilead_api_key_here 使用您的实际API密钥：

MULTILEAD_API_KEY=ml_live_abc123xyz...
MULTILEAD_BASE_URL=https://api.multilead.co
MULTILEAD_TIMEOUT=30
MULTILEAD_DEBUG=false

重要：永远不要承诺你的 .env 文件到版本控制。它已经在里面了 .gitignore.

用法

快速开始

STDIO模式（适用于克劳德桌面/代码/光标）

# 1. Configure environment
cp .env.example .env
nano .env  # Add your MULTILEAD_API_KEY

# 2. Start server
./start.sh

HTTP模式（用于远程访问）

# 1. Configure environment
cp .env.example .env
nano .env  # Add your MULTILEAD_API_KEY

# 2. Start HTTP server
./start-http.sh

服务器将在以下位置可用：

• MCP端点： http://localhost:8000/mcp
• 健康检查： http://localhost:8000/health

高级用法

自定义HTTP配置

# Custom host and port
./start-http.sh --host 127.0.0.1 --port 3000

# Production mode (JSON logs)
./start-http.sh --production

# Debug mode
./start-http.sh --log-level DEBUG

手动启动

工作室：

source .venv/bin/activate
export TRANSPORT=stdio
python server.py

HTTP：

source .venv/bin/activate
export TRANSPORT=http
export PORT=8000
python server.py

健康检查

在HTTP模式下运行时，检查服务器运行状况：

curl http://localhost:8000/health

预期响应：

{
  "status": "healthy",
  "service": "multilead-mcp",
  "version": "1.0.0",
  "transport": "http",
  "api_configured": true
}

部署

Multilead MCP服务器支持三种部署模式：

🚀 FastMCP云（推荐-托管主机）

使用自动扩展、监控和HTTPS端点进行部署的最快方法。

快速入门：

Repository: https://github.com/vanman2024/multilead-mcp
Server Entrypoint: server.py:mcp
Required: MULTILEAD_API_KEY environment variable

Deployment URL: https://multilead-mcp.fastmcp.app/mcp

完整指南： FastMCP云快速入门 详细文件： FastMCP云部署指南

💻 STDIO部署（本地/IDE集成）

用于Claude Desktop、Cursor和Claude Code集成。

快速设置：

1. 复制IDE配置模板：

   # For Claude Desktop (macOS)
   cp docs/setup/claude-desktop-config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

   # For Cursor
   cp docs/setup/cursor-mcp-config.json .cursor/mcp_config.json

   # For Claude Code
   cp docs/setup/claude-code-mcp.json .claude/mcp.json

1. 编辑配置文件并添加您的API密钥

1. 重新启动IDE

详细指南： IDE安装指南

🌐 HTTP部署（自托管远程访问）

用于web服务、远程访问和自定义云部署。

发展：

./start-http.sh

生产： 查看完整 部署指导 用于：

• systemd服务配置
• Docker部署
• nginx反向代理设置
• SSL/TLS配置
• 生产最佳实践

生产特点

服务器包括生产就绪中间件：

• 结构化日志记录：JSON或文本格式，文件轮换
• 请求日志记录：所有请求都记录了时间
• 错误处理：具有适当状态代码的优雅错误响应
• 速率限制：可配置每分钟和每小时限制（默认为100/min、1000/hr）
• 健康检查: /health 监控端点
• 响应时间: X-Response-Time 所有回复的标题

配置：

LOG_LEVEL=INFO              # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=json             # json (production) or text (development)
RATE_LIMIT_PER_MINUTE=100   # Requests per minute
RATE_LIMIT_PER_HOUR=1000    # Requests per hour

文档

完整的部署文档可用：

快速入门：

• FastMCP云快速入门 -复制粘贴就绪的云部署

部署指南：

• FastMCP云部署指南 -托管主机部署
• 自托管部署指南 -完成自托管部署
• 部署检查表 -部署前/部署后检查表

设置指南：

• IDE安装指南 -Claude桌面、光标、Claude代码集成
• 环境变量 -完整的变量引用

配置模板：

• 已准备好使用IDE配置 docs/setup/

可用工具

潜在客户管理（实施了5个工具）

1. create_lead：使用电子邮件、姓名、公司、标签和自定义字段创建新的潜在客户
2. get_lead：按ID检索所有属性的潜在客户
3. list_leads：使用分页和筛选功能列出和筛选潜在客户
4. update_lead：更新潜在客户属性、标记和自定义字段
5. delete_lead：按ID删除潜在客户

Claude的用法示例：

Create a new lead with email "john@example.com", first name "John",
last name "Doe", company "Acme Corp", and tags ["enterprise", "qualified"]

资源

1. multilead://config：服务器配置和API状态
2. multilead://stats：API使用情况统计和帐户信息

提示

1. lead_enrichment_prompt：用AI分析丰富潜在客户数据的模板
2. 活动分析：用于分析活动绩效的模板

API覆盖范围

当前实施情况

• 5个核心潜在客户管理工具（创建、读取、更新、删除、列出）
• 2信息资源
• 2个AI提示模板
• 完整的错误处理和身份验证

计划工具（剩余69个端点）

潜在客户管理（27个以上）:

• 大宗进出口
• 线索评分和丰富
• 标签管理
• 自定义字段操作
• 潜在客户生命周期跟踪
• 重复检测
• 领导分配

活动管理（12个端点）:

• 活动CRUD操作
• 模板管理
• 细分市场定位
• 进度管理
• 性能跟踪
• A/B测试

对话（15个端点）:

• 线程检索
• 消息历史记录
• 参与者跟踪
• 对话分析
• 导出功能

Webhooks（8个端点）:

• Webhook注册
• 事件订阅
• 交货日志
• Webhook测试

分析（7个端点）:

• 领导报告
• 活动分析
• 参与度指标
• 自定义报告

项目结构

multilead-mcp/
├── server.py                          # Main FastMCP server implementation
├── pyproject.toml                     # Project metadata and dependencies
├── .env.example                       # Environment variable template
├── .gitignore                        # Git ignore patterns
├── README.md                         # This file
├── start.sh                          # STDIO startup script
├── start-http.sh                     # HTTP startup script
├── docs/                             # Complete documentation
│   ├── deployment/                   # Deployment guides
│   │   ├── DEPLOYMENT.md            # Complete deployment guide
│   │   ├── DEPLOYMENT_CHECKLIST.md  # Deployment checklist
│   │   └── .env.production          # Production environment template
│   ├── setup/                        # Setup and configuration
│   │   ├── IDE_SETUP.md             # IDE integration guide
│   │   ├── ENVIRONMENT_VARIABLES.md # Environment variables reference
│   │   ├── claude-desktop-config.json  # Claude Desktop template
│   │   ├── cursor-mcp-config.json      # Cursor template
│   │   ├── claude-code-mcp.json        # Claude Code template
│   │   └── http-client-config.json     # HTTP client template
│   └── testing/                      # Testing documentation
├── logs/                             # Server logs (HTTP mode only, gitignored)
└── tests/                            # Test suite (to be implemented)
    └── test_server.py

发展

添加新工具

遵循中的模式 server.py:

@mcp.tool()
async def your_new_tool(
    param1: str,
    param2: Optional[int] = None
) -> Dict[str, Any]:
    """
    Tool description for LLM

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Response data from API
    """
    result = await client.request(
        "GET",
        "/v1/your-endpoint",
        params={"param1": param1, "param2": param2}
    )
    return result

代码质量

# Format code
black server.py

# Lint code
ruff check server.py

# Type checking (optional)
mypy server.py

安全最佳实践

• 切勿硬编码API密钥 源代码中
• 始终使用环境变量作为机密
• 这 .env 文件在 .gitignore 防止意外犯罪
• API密钥从未被记录或暴露在错误消息中
• 使用 .env.example 作为仅包含占位符的模板

故障排除

身份验证错误

Error: Authentication failed. Please check your MULTILEAD_API_KEY.

解决方案：验证您的API密钥是否正确并且在 https://app.multilead.co/settings/api

超时错误

Error: Request timed out after 30 seconds.

解决方案：增加您的超时时间 .env 文件：

MULTILEAD_TIMEOUT=60

速率限制

Error: Rate limit exceeded. Please wait before making more requests.

解决方案：API有费率限制。请等待几分钟，然后重试。考虑为高容量操作实现请求队列。

连接错误

Error: Network error while connecting to Multilead API

解决方案:

1. 检查您的互联网连接
2. 验证 MULTILEAD_BASE_URL 是正确的
3. 检查Multilead API是否运行

API 文档

有关API完整参考资料，请访问：

• 官方文件: https://docs.multilead.co/api-reference
• API仪表板: https://app.multilead.co/settings/api

FastMCP文档

了解有关FastMCP的更多信息：

• 入门指南: https://gofastmcp.com/getting-started/welcome
• 服务器指南: https://gofastmcp.com/servers/server
• 工具: https://gofastmcp.com/servers/tools

贡献

欢迎投稿！要添加更多端点，请执行以下操作：

1. 查看Multilead API文档
2. 按照现有模式添加工具功能
3. 包含正确的类型提示和文档字符串
4. 手动测试端点
5. 使用新工具更新此README

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于以下问题：

• 此MCP服务器：在存储库中打开问题
• 多导线API：联系方式 多引线支持
• FastMCP框架：参观 FastMCP文档

更新日志

版本1.0.0（2025-11-05）

• 初始版本
• 实施了5个核心潜在客户管理工具
• 2信息资源
• 2个AI提示模板
• 完全身份验证和错误处理
• 74个API端点的生产就绪基础