Smartlead MCP (Vibe Marketer)

= 18" />

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 --仅在一个项目中可用

克劳德桌面版

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

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

1. 重新启动克劳德桌面
2. 寻找锤子图标——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个工具）

线索（11个工具）

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

活动统计（4个工具）

分析（2个工具）

全球分析（12个工具）

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

Webhooks（6个工具）

主收件箱（1个工具）

客户管理（1个工具）

智能交付（1个工具）

______________________________________________________________________

项目结构

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

添加新工具

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

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("GET", `/endpoint/${param}`);
      return ok(JSON.stringify(result, null, 2));
    } catch (e) {
      return err(e);
    }
  }
);

1. 注册于 src/tools/index.ts
2. 部署： 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/参考

______________________________________________________________________

技术栈

______________________________________________________________________

许可证

麻省理工学院