多引线开放式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-mcp2.创建虚拟环境
使用紫外线（推荐）：
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 Windows3.安装依赖项
使用紫外线：
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.shHTTP模式（用于远程访问）
# 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.pyHTTP：
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集成。
快速设置：
- 复制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- 编辑配置文件并添加您的API密钥
- 重新启动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配置
docs/setup/
可用工具
潜在客户管理（实施了5个工具）
- create_lead：使用电子邮件、姓名、公司、标签和自定义字段创建新的潜在客户
- get_lead：按ID检索所有属性的潜在客户
- list_leads：使用分页和筛选功能列出和筛选潜在客户
- update_lead：更新潜在客户属性、标记和自定义字段
- 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"]资源
- multilead://config：服务器配置和API状态
- multilead://stats：API使用情况统计和帐户信息
提示
- lead_enrichment_prompt：用AI分析丰富潜在客户数据的模板
- 活动分析：用于分析活动绩效的模板
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解决方案:
- 检查您的互联网连接
- 验证
MULTILEAD_BASE_URL是正确的 - 检查Multilead API是否运行
API 文档
有关API完整参考资料，请访问：
FastMCP文档
了解有关FastMCP的更多信息：
- 入门指南: https://gofastmcp.com/getting-started/welcome
- 服务器指南: https://gofastmcp.com/servers/server
- 工具: https://gofastmcp.com/servers/tools
贡献
欢迎投稿！要添加更多端点，请执行以下操作：
- 查看Multilead API文档
- 按照现有模式添加工具功能
- 包含正确的类型提示和文档字符串
- 手动测试端点
- 使用新工具更新此README
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
对于以下问题：
更新日志
版本1.0.0（2025-11-05）
- 初始版本
- 实施了5个核心潜在客户管理工具
- 2信息资源
- 2个AI提示模板
- 完全身份验证和错误处理
- 74个API端点的生产就绪基础