Instantly MCP 服务器

用于 Instantly API v2 的 MCP 服务器，提供对电子邮件营销活动和潜在客户管理功能的访问。

关于 Instantly API

Instantly API v2 是一个 RESTful API，提供对 Instantly 平台的各种资源和功能的访问，包括：

• 营销活动管理
• 潜在客户管理
• 电子邮件处理和验证
• 分析
• 账户管理
• 黑名单管理
• 以及更多

此 MCP 服务器实现了这些端点的子集，以便轻松访问最常用的功能。

API 参考

完整的 Instantly API v2 文档可在以下位置找到：

• API Explorer
• API Schemas
• Analytics Endpoints

所有 API 请求的基本 URL 为：https://api.instantly.ai/api/v2

工具

此 MCP 服务器实现了以下工具，这些工具映射到 Instantly API v2 端点：

1. instantly_create_lead

   • API 端点: POST /api/v2/leads
   • 创建新的潜在客户
   • 输入:
     • email (字符串)
     • first_name (可选字符串)
     • last_name (可选字符串)
     • company_name (可选字符串)
     • campaign (可选字符串, uuid)
     • list_id (可选字符串, uuid)
     • personalization (可选字符串)
     • website (可选字符串)
     • phone (可选字符串)
     • custom_variables (可选对象)

2. instantly_get_lead

   • API 端点: GET /api/v2/leads/{id}
   • 通过 ID 获取潜在客户的详细信息
   • 输入: id (字符串, uuid)
   • 返回: 潜在客户详细信息

3. instantly_list_leads

   • API 端点: POST /api/v2/leads/list
   • 列出具有可选过滤器的潜在客户
   • 输入:
     • campaign (可选字符串, uuid)
     • list_id (可选字符串, uuid)
     • limit (可选数字)
     • starting_after (可选字符串)
   • 返回: 潜在客户数组

4. instantly_update_lead

   • API 端点: PATCH /api/v2/leads/{id}
   • 更新潜在客户的信息
   • 输入:
     • id (字符串, uuid)
     • first_name (可选字符串)
     • last_name (可选字符串)
     • company_name (可选字符串)
     • personalization (可选字符串)
     • website (可选字符串)
     • phone (可选字符串)
     • custom_variables (可选对象)

5. instantly_delete_lead

   • API 端点: DELETE /api/v2/leads/{id}
   • 删除潜在客户
   • 输入: id (字符串, uuid)

6. instantly_list_campaigns

   • API 端点: GET /api/v2/campaigns
   • 列出具有分页支持的营销活动
   • 输入:
     • limit (可选数字, 默认 5, 最大 100)
     • starting_after (可选字符串) - 对于分页，使用上一个响应中的 next_starting_after 值
     • status (可选数字) - 按状态过滤营销活动 (0: 草稿, 1: 活动, 2: 暂停, 3: 完成, 4: 运行子序列)
   • 返回: 具有分页信息的营销活动数组
   • 分页:
     • 首次请求: 调用时不带 starting_after
     • 后续页面: 使用上一个响应中的 next_starting_after 值
     • 当没有更多页面时，响应将不包含 next_starting_after 值
   • 示例: 要仅获取活动营销活动，请使用 status: 1

7. instantly_get_campaign

   • API 端点: GET /api/v2/campaigns/{id}
   • 获取营销活动的详细信息
   • 输入: id (字符串, uuid)
   • 返回: 营销活动详细信息

8. instantly_get_warmup_analytics

   • API 端点: POST /api/v2/accounts/warmup-analytics
   • 获取指定电子邮件帐户的预热分析
   • 输入: emails (字符串数组)
   • 返回: 电子邮件预热性能的健康评分和指标
   • 有助于监控电子邮件送达率和帐户健康状况

9. instantly_test_account_vitals

   • API 端点: POST /api/v2/accounts/test/vitals
   • 测试 Instantly 工作区中电子邮件帐户的健康状况和连接性
   • 输入: accounts (字符串数组) - 可以一次测试多个电子邮件地址
   • 返回:
     • 总体测试状态
     • 成功和失败帐户的摘要
     • 每个帐户的详细信息，包括提供商详细信息
     • 失败帐户的故障排除建议
   • 帮助识别电子邮件帐户配置、身份验证和 API 访问的问题
   • 示例: {"accounts": ["user@example.com", "sales@company.com"]}

10. instantly_get_campaign_analytics

    • API 端点: GET /api/v2/campaigns/analytics
    • 获取指定时间段内营销活动的绩效指标
    • 输入:
      • id (可选字符串) - 特定营销活动的营销活动 ID
      • start_date (字符串) - YYYY-MM-DD 格式的开始日期
      • end_date (字符串) - YYYY-MM-DD 格式的结束日期
    • 返回: 综合指标，包括打开率、回复率、潜在客户计数和商机数据

分析端点

Instantly API 提供了强大的分析端点来监控您的电子邮件营销活动和帐户的绩效：

1. 获取预热分析

   • API 端点: POST /api/v2/accounts/warmup-analytics
   • 描述: 检索指定电子邮件帐户的预热分析数据
   • 必需范围: accounts:read, accounts:all, all:read, 或 all:all
   • 请求正文:

     {
       "emails": ["user@example.com"]
     }
     

   • 响应: 提供有关已发送电子邮件、收件箱放置、垃圾邮件放置和已接收电子邮件的每日和汇总数据，以及每个帐户的健康评分

2. 测试帐户重要信息

   • API 端点: POST /api/v2/accounts/test/vitals
   • 描述: 测试电子邮件帐户的健康状况和连接性
   • 必需范围: accounts:read, accounts:all, all:read, 或 all:all
   • 请求正文:

     {
       "accounts": ["user@example.com"]
     }
     

   • 响应: 返回成功和失败列表，其中包含有关帐户状态和任何检测到的问题的详细信息

3. 获取营销活动分析

   • API 端点: GET /api/v2/campaigns/analytics
   • 描述: 检索一个或多个营销活动的绩效指标
   • 查询参数:
     • id (可选): 特定营销活动的营销活动 ID
     • start_date: 分析期间的开始日期
     • end_date: 分析期间的结束日期
   • 响应: 返回综合营销活动统计信息，包括：
     • 潜在客户总数
     • 已联系的潜在客户数
     • 电子邮件打开数
     • 回复数
     • 退回数
     • 取消订阅数
     • 完成数
     • 已发送电子邮件数
     • 已联系的新潜在客户数
     • 商机总数
     • 商机总价值

有关请求参数和响应格式的详细信息，请参阅 Instantly Analytics API 文档。

其他 Instantly API 端点

Instantly API v2 包含此 MCP 服务器中未实现的许多其他端点，包括：

• 营销活动管理:

  • 创建营销活动: POST /api/v2/campaigns
  • 激活营销活动: POST /api/v2/campaigns/{id}/activate
  • 暂停营销活动: POST /api/v2/campaigns/{id}/pause
  • 更新营销活动: PATCH /api/v2/campaigns/{id}

• 电子邮件:

  • 回复电子邮件: POST /api/v2/emails/reply
  • 列出电子邮件: GET /api/v2/emails
  • 获取电子邮件: GET /api/v2/emails/{id}
  • 统计未读电子邮件: GET /api/v2/emails/unread/count

• 帐户管理:

  • 这些端点现在可用作此 MCP 服务器中的工具！ 请参阅下面的“帐户管理工具”部分。

• 电子邮件验证:

  • 验证电子邮件: POST /api/v2/email-verification

• 潜在客户列表:

  • 创建列表: POST /api/v2/lead-lists
  • 列出潜在客户列表: GET /api/v2/lead-lists

有关所有可用端点的完整参考，请参阅 Instantly API Explorer。

设置

API 密钥

从您的 Instantly 帐户设置中获取 Instantly API 密钥：

1. 转到 Instantly 仪表板中的集成
2. 单击左侧边栏中的“API 密钥”部分
3. 单击“创建 API 密钥”按钮
4. 输入 API 密钥的名称
5. 选择您希望此密钥有权访问的范围
6. 创建并复制您的 API 密钥（注意：它只会显示一次）

与 Claude Desktop 一起使用

将以下内容添加到您的 claude_desktop_config.json：

Docker

{
  "mcpServers": {
    "instantly": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "INSTANTLY_API_KEY",
        "mcp/instantly"
      ],
      "env": {
        "INSTANTLY_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-instantly"
      ],
      "env": {
        "INSTANTLY_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

构建

Docker 构建:

docker build -t mcp/instantly -f Dockerfile .

身份验证

Instantly API v2 使用 Bearer 令牌身份验证。 您的 API 密钥应包含在所有请求的 Authorization 标头中：

Authorization: Bearer YOUR_API_KEY

当您通过环境变量提供 API 密钥时，MCP 服务器会自动处理此问题。

许可证

此 MCP 服务器已获得 MIT 许可证的许可。 这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。 有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。

帐户管理工具

此 MCP 服务器实现了以下帐户管理工具：

1. instantly_create_account

   • API 端点: POST /api/v2/accounts
   • 在 Instantly 中创建一个新的电子邮件帐户
   • 输入:
     • email (字符串): 帐户的电子邮件地址
     • first_name (字符串): 与帐户关联的名字
     • last_name (字符串): 与帐户关联的姓氏
     • provider_code (数字): 提供商代码 (1: 自定义 IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)
     • imap_username (字符串): IMAP 用户名
     • imap_password (字符串): IMAP 密码
     • imap_host (字符串): IMAP 主机 (例如 imap.gmail.com)
     • imap_port (数字): IMAP 端口 (例如 993)
     • smtp_username (字符串): SMTP 用户名
     • smtp_password (字符串): SMTP 密码
     • smtp_host (字符串): SMTP 主机 (例如 smtp.gmail.com)
     • smtp_port (数字): SMTP 端口 (例如 587)
     • daily_limit (可选数字): 每日电子邮件发送限制
     • tracking_domain_name (可选字符串): 跟踪域名

2. instantly_list_accounts

   • API 端点: GET /api/v2/accounts
   • 在 Instantly 中列出电子邮件帐户，并自动分页
   • 输入:
     • limit (可选数字): 每页返回的帐户数（最大 100，默认 10）
     • starting_after (可选字符串): 上一页中最后一项的 ID - 用于分页
     • search (可选字符串): 用于过滤帐户的搜索词
     • status (可选数字): 状态过滤器 (1: 活动, 2: 暂停, -1: 连接错误, -2: 软退回错误, -3: 发送错误)
     • provider_code (可选数字): 提供商代码过滤器 (1: 自定义 IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)
     • fetch_all (可选布尔值): 是否自动获取所有页面并提供综合摘要。 使用此选项可获取有关所有帐户的信息。
   • 分页:
     • 默认行为: 返回单个结果页面，其中包含指向下一页的链接
     • 使用 fetch_all=true: 自动获取所有页面并返回所有帐户的综合摘要，包括：
       • 帐户总数
       • 按提供商的帐户分布
       • 按状态的帐户分布
       • 用于参考的帐户示例

3. instantly_get_account

   • API 端点: GET /api/v2/accounts/{email}
   • 获取 Instantly 中特定电子邮件帐户的详细信息
   • 输入: email (字符串): 要检索的帐户的电子邮件地址

4. instantly_update_account

   • API 端点: PATCH /api/v2/accounts/{email}
   • 更新 Instantly 中的现有电子邮件帐户
   • 输入:
     • email (字符串): 要更新的帐户的电子邮件地址
     • first_name (可选字符串): 与帐户关联的名字
     • last_name (可选字符串): 与帐户关联的姓氏
     • daily_limit (可选数字): 每日电子邮件发送限制
     • tracking_domain_name (可选字符串): 跟踪域名
     • skip_cname_check (可选布尔值): 是否跳过跟踪域的 CNAME 检查
     • remove_tracking_domain (可选布尔值): 是否从帐户中删除跟踪域

5. instantly_delete_account

   • API 端点: DELETE /api/v2/accounts/{email}
   • 从 Instantly 中删除电子邮件帐户
   • 输入: email (字符串): 要删除的帐户的电子邮件地址

6. instantly_pause_account

   • API 端点: POST /api/v2/accounts/{email}/pause
   • 暂停 Instantly 中的电子邮件帐户
   • 输入: email (字符串): 要暂停的帐户的电子邮件地址

7. instantly_resume_account

   • API 端点: POST /api/v2/accounts/{email}/resume
   • 恢复 Instantly 中已暂停的电子邮件帐户
   • 输入: email (字符串): 要恢复的帐户的电子邮件地址

工具测试状态

我们已经彻底测试了此 MCP 服务器中实现的所有工具，以确保它们与 Instantly API v2 配合正常。 以下是测试状态的摘要：

#	工具名称	状态	备注
1	instantly_list_campaigns	✅ 已验证	成功列出具有分页支持的营销活动
2	instantly_list_leads	❌ 不工作	持久的 API 错误 - 尝试列出潜在客户时出现“无效的电子邮件地址”
3	instantly_delete_lead	✅ 已验证	成功按 ID 或电子邮件地址删除潜在客户
4	instantly_create_lead	✅ 已验证	成功使用正确的数据创建新的潜在客户
5	instantly_get_lead	✅ 已验证	成功按 ID 检索潜在客户详细信息
6	instantly_update_lead	✅ 已验证	成功更新现有潜在客户信息
7	instantly_list_accounts	✅ 已验证	成功列出所有电子邮件帐户以及统计信息
8	instantly_get_account	✅ 已验证	成功检索详细的帐户信息
9	instantly_test_account_vitals	✅ 已验证	成功检索帐户健康信息
10	instantly_get_warmup_analytics	✅ 已验证	成功检索帐户的预热数据

有关测试过程和结果的更多详细信息，请参阅存储库中的 Testing.md。

已知问题

• 当前，当尝试在没有特定电子邮件过滤器的情况下列出潜在客户时，instantly_list_leads 工具会返回“无效的电子邮件地址”API 错误。 我们已经尝试了多种方法来解决此问题，包括：

  • 使用 contacts 数组参数进行电子邮件搜索
  • 实现带有空请求正文的自动重试
  • 各种参数格式化方法

  我们将继续努力在未来的版本中解决此问题。

开发设置

如果您想为此项目做出贡献或在本地运行它以进行开发：

1. 克隆存储库：

   git clone https://github.com/bcharleson/Instantly-MCP.git
   cd Instantly-MCP
   

2. 安装依赖项：

   npm install
   

3. 在根目录中创建一个包含您的 Instantly API 密钥的 .env 文件：

   INSTANTLY_API_KEY=your_api_key_here
   

   ⚠️ 重要提示: 永远不要将您的 .env 文件或 API 密钥提交到版本控制。 .env 文件包含在 .gitignore 中，以防止意外提交。

4. 构建项目：

   npm run build
   

5. 运行服务器：

   node dist/index.js
   

贡献

欢迎贡献！ 如果您想贡献：

1. Fork 存储库
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 提交更改 (git commit -m 'Add some amazing feature')
5. 推送到分支 (git push origin feature/amazing-feature)
6. 打开一个 Pull Request

在提交 pull request 之前，请确保：

• 您的代码遵循项目的编码风格
• 您已为新功能添加了测试
• 所有测试均通过
• 如果需要，您已更新文档