即时 MCP 服务器

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

关于 Instantly API

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

• 营销活动管理

• 潜在客户管理

• 电子邮件处理和验证

• 分析

• 帐户管理

• 黑名单管理

• 以及更多

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

Related MCP server: SendGrid MCP Server

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. 打开拉取请求

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

• 您的代码遵循项目的编码风格

• 您已添加新功能的测试

• 所有测试均通过

• 您已根据需要更新了文档