即时 MCP 服务器

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

关于 Instantly API

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

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

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

API 参考

完整的 Instantly API v2 文档可在以下位置获取：

• API 浏览器
• API 模式
• 分析端点

所有 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
   • 测试即时工作区中电子邮件帐户的健康状况和连接性
   • 输入： 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 文档。

附加即时 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

NPX

建造

Docker 构建：

验证

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

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

执照

此 MCP 服务器采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。

账户管理工具

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

1. instantly_create_account
   • API 端点： POST /api/v2/accounts
   • 立即创建新的电子邮件帐户
   • 输入：
     • 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
   • 使用自动分页功能立即列出电子邮件帐户
   • 输入：
     • 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}
   • 立即获取特定电子邮件帐户的详细信息
   • 输入： email （字符串）：要检索的帐户的电子邮件地址
4. instantly_update_account
   • API 端点： PATCH /api/v2/accounts/{email}
   • 立即更新现有电子邮件帐户
   • 输入：
     • 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}
   • 立即删除电子邮件帐户
   • 输入： email （字符串）：要删除的帐户的电子邮件地址
6. instantly_pause_account
   • API 端点： POST /api/v2/accounts/{email}/pause
   • 立即暂停电子邮件帐户
   • 输入： email （字符串）：要暂停的帐户的电子邮件地址
7. instantly_resume_account
   • API 端点： POST /api/v2/accounts/{email}/resume
   • 立即恢复已暂停的电子邮件帐户
   • 输入： email （字符串）：要恢复的帐户的电子邮件地址

工具测试状态

我们已经彻底测试了此 MCP 服务器中实现的所有工具，以确保它们能够与 Instantly API v2 完美兼容。以下是测试状态摘要：

有关测试过程和结果的更多详细信息，请参阅存储库中的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 文件包含在.env中.gitignore以防止意外提交。

4. 构建项目：
   npm run build
5. 运行服务器：
   node dist/index.js

贡献

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

1. 分叉存储库
2. 创建功能分支（ git checkout -b feature/amazing-feature ）
3. 进行更改
4. 提交您的更改（ git commit -m 'Add some amazing feature' ）
5. 推送到分支（ git push origin feature/amazing-feature ）
6. 打开拉取请求

在提交拉取请求之前，请确保：

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