使用说明

SmartLead MCP服务器

全面的模型上下文协议（MCP）服务器 SmartLead.ai 冷邮件平台。部署为 Cloudflare工作人员 并将其连接到Claude、Cursor、Windsurf或任何兼容MCP的客户端，通过自然语言管理您的整个SmartLead帐户。

67工具 涵盖整个SmartLead API：活动、潜在客户、电子邮件帐户、序列、网络挂钩、分析、预热、主收件箱等。

建筑

┌─────────────────────────┐
│  Claude / MCP Client    │
│  (Desktop, Code, etc.)  │
└───────────┬─────────────┘
            │ MCP Protocol (SSE)
            v
┌─────────────────────────┐
│   Cloudflare Worker      │
│   (Durable Object)       │
│                          │
│  ┌────────────────────┐  │
│  │  Rate Limiter      │  │
│  │  10 req / 2 sec    │  │
│  └────────┬───────────┘  │
│           │              │
│  ┌────────v───────────┐  │
│  │  Retry + Backoff   │  │
│  │  3 retries, jitter │  │
│  └────────┬───────────┘  │
└───────────┼──────────────┘
            │ HTTPS + API Key
            v
┌─────────────────────────┐
│   SmartLead API          │
│   server.smartlead.ai    │
└─────────────────────────┘

Cloudflare Workers --无服务器、全球分布式、~50ms冷启动
耐用物品 --跨请求的持久MCP代理状态
令牌桶速率限制器 --每2秒10个请求（符合SmartLead限制）
自动重试 --429/5xx错误的指数回退和抖动（最多3次重试）
25秒超时 --安全地低于Cloudflare的30秒硬限制

快速开始

1.克隆和安装

git clone https://github.com/drleadflow/smartlead-mcp.git
cd smartlead-mcp
npm install

2.配置

复制示例配置并添加您的凭据：

cp wrangler.toml.example wrangler.toml

编辑 wrangler.toml:

name = "smartlead-mcp"
account_id = "YOUR_CLOUDFLARE_ACCOUNT_ID"    # From Cloudflare dashboard
# ...

[vars]
SMARTLEAD_API_KEY = "YOUR_SMARTLEAD_API_KEY"  # From SmartLead > Settings > API Keys

提示： 为了地方发展，创建一个 .dev.vars 文件改为：
SMARTLEAD_API_KEY=your-key-here

3.部署

npx wrangler deploy

您的MCP服务器现在位于：

https://smartlead-mcp.YOUR-SUBDOMAIN.workers.dev/mcp

4.验证

curl https://smartlead-mcp.YOUR-SUBDOMAIN.workers.dev/mcp

联系克劳德

克劳德代码（CLI）

添加到您的Claude代码配置中。编辑 ~/.claude.json:

{
  "mcpServers": {
    "smartlead-mcp": {
      "type": "url",
      "url": "https://smartlead-mcp.YOUR-SUBDOMAIN.workers.dev/mcp"
    }
  }
}

重新启动克劳德代码。全部67 sl_* 工具立即可用。

范围选项：

~/.claude.json --适用于所有项目（用户范围）
PROJECT_DIR/.claude/settings.json --仅在一个项目中可用

克劳德桌面版

打开设置 > 开发者 > 编辑配置
增添 mcpServers:

{
  "mcpServers": {
    "smartlead-mcp": {
      "type": "url",
      "url": "https://smartlead-mcp.YOUR-SUBDOMAIN.workers.dev/mcp"
    }
  }
}

重新启动克劳德桌面
寻找锤子图标——MCP工具已连接

Cursor/Windsurf/其他MCP客户端

将您的MCP客户端指向：

https://smartlead-mcp.YOUR-SUBDOMAIN.workers.dev/mcp

服务器通过服务器发送事件（SSE）发出标准MCP。MCP端不需要身份验证——SmartLead API密钥安全地存储在Cloudflare Worker中。

连接后可以做什么

问克劳德这样的问题：

“列出我的所有SmartLead活动”
“显示活动12345的回复率”
“创建一个名为Q1 Outreach的新活动”
“将这50条潜在客户添加到活动12345”
“检查我所有电子邮件帐户的预热统计信息”
“为活动12345的回复设置一个webhook”
“我所有帐户的域名健康状况如何？”

全部67个工具

活动（12个工具）

工具	说明
`sl_list_campaigns`	列出所有活动
`sl_get_campaign`	按ID获取活动详细信息
`sl_create_campaign`	创建新活动
`sl_update_campaign_status`	启动、暂停或停止活动
`sl_update_campaign_settings`	更新活动名称、跟踪、取消订阅文本
`sl_update_campaign_schedule`	设置时区、发送时间、每日限制
`sl_get_campaign_sequence`	获取电子邮件序列步骤
`sl_save_campaign_sequence`	用A/B变体创建/替换电子邮件序列
`sl_list_campaign_email_accounts`	列出分配给活动的电子邮件帐户
`sl_add_email_account_to_campaign`	为活动分配电子邮件帐户
`sl_remove_email_account_from_campaign`	取消分配电子邮件帐户
`sl_delete_campaign`	删除活动（不可逆）

线索（11个工具）

工具	说明
`sl_add_leads_to_campaign`	批量添加潜在客户（按100批处理，最多350/次呼叫）
`sl_list_campaign_leads`	列出活动中的所有潜在客户
`sl_get_lead_by_email`	通过电子邮件地址查找潜在客户
`sl_delete_lead_from_campaign`	从活动中删除潜在客户
`sl_pause_lead_in_campaign`	暂停潜在客户的电子邮件投递
`sl_resume_lead_in_campaign`	恢复暂停的潜在客户
`sl_update_lead`	更新潜在客户数据（姓名、公司、自定义字段）
`sl_unsubscribe_lead`	全球取消订阅所有活动
`sl_get_lead_categories`	获取所有潜在客户类别
`sl_export_campaign_leads`	以CSV格式导出活动
`sl_get_all_leads_activities`	使用分页功能获取潜在客户活动事件

电子邮件帐户（8个工具）

工具	说明
`sl_list_email_accounts`	列出所有发送帐户
`sl_get_email_account`	获取帐户详细信息（SMTP状态，每日发送）
`sl_get_warmup_stats`	获取预热信誉（已发送、收件箱、垃圾邮件计数）
`sl_create_email_account`	创建SMTP/IMAP电子邮件帐户
`sl_create_oauth_email_account`	通过OAuth添加Gmail/Outlook
`sl_update_email_account`	更新显示名称、每日限额、签名
`sl_delete_email_account`	软删除电子邮件帐户
`sl_update_warmup_settings`	启用/禁用预热，设置每日升级

活动统计（4个工具）

工具	说明
`sl_get_campaign_analytics`	活动的每封电子邮件分析
`sl_get_campaign_analytics_by_date`	按日期细分的分析
`sl_get_campaign_lead_stats`	潜在客户级别统计
`sl_get_campaign_mailbox_stats`	每个邮箱的发送统计信息

分析（2个工具）

工具	说明
`sl_get_campaign_stats`	活动统计数据（发送、打开、点击、回复、反弹）
`sl_get_all_campaign_analytics`	所有活动的汇总分析

全球分析（12个工具）

工具	说明
`sl_get_overall_analytics`	所有活动的总体统计数据
`sl_get_analytics_campaign_list`	带有分析功能的活动列表
`sl_get_analytics_campaign_overall`	活动级别总体统计数据
`sl_get_analytics_campaign_response`	活动响应分析
`sl_get_analytics_campaign_status`	活动状态细分
`sl_get_analytics_followup_reply_rate`	后续序列回复率
`sl_get_analytics_lead_to_reply_time`	导致回复时间分析
`sl_get_analytics_leads_for_first_reply`	首次回复所需的线索
`sl_get_analytics_daywise_overall`	日常总体分析
`sl_get_analytics_daywise_by_sent_time`	按发送时间分析
`sl_get_analytics_daywise_positive_replies`	按日积极回复
`sl_get_analytics_positive_replies_by_sent_time`	按发送时间分列的肯定答复

全球分析扩展（9个工具）

工具	说明
`sl_get_analytics_lead_overall`	领导层整体分析
`sl_get_analytics_lead_category_response`	按潜在客户类别分列的回复率
`sl_get_analytics_domain_health`	域名声誉和健康状况
`sl_get_analytics_account_health`	每个帐户发送健康信息
`sl_get_analytics_provider_performance`	ESP提供商绩效
`sl_get_analytics_client_list`	带有分析功能的客户列表
`sl_get_analytics_client_overall`	客户级总体统计数据
`sl_get_analytics_monthly_client_count`	每月客户数趋势
`sl_get_analytics_team_board`	团队绩效板

Webhooks（6个工具）

工具	说明
`sl_set_campaign_webhook`	为活动事件注册webhook
`sl_list_campaign_webhooks`	列出活动的webhooks
`sl_delete_campaign_webhook`	删除活动webhook
`sl_create_global_webhook`	创建帐户级webhook
`sl_get_webhook`	按ID获取webhook详细信息
`sl_delete_global_webhook`	删除全局webhook

主收件箱（1个工具）

工具	说明
`sl_fetch_inbox_replies`	获取包含对话历史记录的完整回复消息

客户管理（1个工具）

工具	说明
`sl_create_client`	创建或保存客户帐户

智能交付（1个工具）

工具	说明
`sl_get_smart_delivery_providers`	获取智能配送提供商ID

项目结构

smartlead-mcp/
  src/
    index.ts                          # Entry point -- McpAgent + Durable Object
    client.ts                         # HTTP client with rate limiting + retry
    config.ts                         # Constants (BASE_URL, BATCH_SIZE)
    types.ts                          # Env interface
    helpers.ts                        # ok() / err() response helpers
    tools/
      index.ts                        # Tool registration orchestrator
      campaigns.ts                    # 12 campaign tools
      leads.ts                        # 11 lead tools
      accounts.ts                     # 8 email account tools
      analytics.ts                    # 2 core analytics tools
      statistics.ts                   # 4 campaign statistics tools
      global-analytics.ts             # 12 global analytics tools
      global-analytics-extended.ts    # 9 extended analytics tools
      analytics-helpers.ts            # Shared analytics query schema
      webhooks.ts                     # 6 webhook tools
      master-inbox.ts                 # 1 master inbox tool
      clients.ts                      # 1 client management tool
      smart-delivery.ts               # 1 smart delivery tool
  wrangler.toml                       # Cloudflare Worker config
  wrangler.toml.example               # Template with placeholders
  package.json
  tsconfig.json

运作原理

速率限制

服务器实现了与SmartLead的API限制相匹配的令牌桶速率限制器：

每2秒10个请求 （保守，SmartLead允许10/sec）
当bucket为空时，请求会自动排队
没有请求被丢弃——它们等待可用的令牌

重试逻辑

失败的请求会自动以指数回退方式重试：

可重试： 429（速率限制）、500、502、503、504
未重试： 400、401、404、422（立即失效）
后退： 具有随机抖动的1s、2s、4s
最大重试次数： 3
标头后重试： 在场时受到尊重

认证

SmartLead通过查询参数使用API密钥身份验证：

https://server.smartlead.ai/api/v1/endpoint?api_key=YOUR_KEY

API密钥存储在Cloudflare Worker环境中，从不暴露给MCP客户端。

发展

本地开发人员

# Create local env file
echo 'SMARTLEAD_API_KEY=your-key' > .dev.vars

# Start dev server
npx wrangler dev

# MCP endpoint available at http://localhost:8787/mcp

类型检查

npx tsc --noEmit

添加新工具

在中选择适当的文件 src/tools/ （或创建一个新的）
遵循以下模式：

server.tool(
  "sl_your_tool_name",                    // sl_ prefix, snake_case
  "Human-readable description",           // What it does
  {                                       // Zod parameter schema
    param: z.string().describe("..."),
  },
  async ({ param }) => {                  // Handler
    try {
      const client = new SmartLeadClient(env.SMARTLEAD_API_KEY);
      const result = await client.request<unknown>("GET", `/endpoint/${param}`);
      return ok(JSON.stringify(result, null, 2));
    } catch (e) {
      return err(e);
    }
  }
);

注册于 src/tools/index.ts
部署： npx wrangler deploy

故障排除

“无效的API密钥”错误

你的 SMARTLEAD_API_KEY 错误或未设置。验证：

curl "https://server.smartlead.ai/api/v1/campaigns?api_key=YOUR_KEY"

工具未出现在Claude中

部署后，重新启动Claude Code或Claude Desktop以刷新MCP连接。持久对象缓存每个会话的工具列表。

电子邮件帐户上的SMTP失败

invalid_grant 错误意味着Google OAuth令牌已过期。必须在SmartLead UI（设置>电子邮件帐户>重新连接）中修复此问题。无法通过API解决。

速率限制错误

内置的速率限制器应该可以防止这些。如果你仍然看到429个错误，SmartLead可能已经收紧了限制。调整 src/client.ts:

const rateLimiter = new RateLimiter(5, 2000);  // More conservative

Cloudflare部署失败

确保您已登录： npx wrangler login

检查你的 account_id 在 wrangler.toml 匹配您的Cloudflare帐户。

SmartLead API参考

基本URL: https://server.smartlead.ai/api/v1
认证： API密钥作为 ?api_key= 查询参数
费率限制： 10要求/秒（标准），120要求/分钟（专业）
文件： api.smartlead.ai/参考

技术栈

组件	技术
运行时间	Cloudflare Workers
国家	耐用物品
协议	模型上下文协议（MCP）
MCP-SDK	@模型上下文协议/sdk
代理商基地	代理（Cloudflare McpAgent）
验证	佐德
语言	TypeScript （严格模式）

许可证

麻省理工学院