instantly-ai-mcp

一个用于 Instantly.ai v2 REST API 的 MCP 服务器，它编码的是 API 实际 的行为，而不是轻信其文档。下面每一个怪癖都是针对线上 API 复现的，不是从更新日志或论坛帖子抄来的，并且会持续被核验：npm run verify-gotchas 会按需重新探测线上账户，并标记任何与现实行为已偏离本文档所述内容的声明（参见 为什么这张表是机器核验的——这是手动核验，不属于 CI 的一部分）。

那些怪癖

这张表就是这个仓库存在的原因。每个基于此 API 构建的服务器最终都会以艰难的方式重新发现这些问题——通常是在盯着一个看起来像是错误信息的报错时。于 2026-08-21 线上捕获；关于如何保持其真实性，请参见 为什么这张表是机器核验的。

关于有趣行的说明：

• #3 —— 线上探测发送了 campaign_ids: [id]，返回了 5 个线索，全部 5 个都属于其他活动。该参数不只是被忽略，它静默地成为一个无效过滤器；单数的 campaign 参数才是真正限定查询范围的参数。list_leads 正是因为这个原因会核验每个返回线索自身的 campaign 字段，并在不信任过滤器时发出警告。

• #4 —— 这在 2026-08-17 被记录为 成立，并在 2026-08-21 翻转为 被推翻。?id= 现在能正确地将分析结果过滤到单个活动。下面会说明为什么这个翻转正是这个仓库存在的全部意义。

• #5 —— 在 2026-08-17 时为 无法验证（账户中不存在草稿活动可供测试），随后被 线上集成测试套件（INSTANTLY_LIVE_TEST=1）确认为 成立，该套件会创建一个一次性的草稿活动，并确认未过滤的 /campaigns/analytics 会将其省略。上面的 成立 是通过这种方式验证的，不是通过 verify-gotchas 的只读探测：当账户中不存在草稿活动时，该探测会返回 无法验证（它从不创建草稿活动），因此针对无草稿账户运行它，预期会显示“无法重新核验”，而不是与这一行相矛盾。list_campaigns 正是因为这个原因从 GET /campaigns 读取数据——该端点确实包含草稿。

• #6、#7、#8 是 无法验证，这是只读探测在原则上的结果，而不是偶然： #6 和 #7 需要一次线上写入（创建活动 / webhook），而探测脚本刻意永远不会对真实账户执行这种操作；#8 是一个间歇性的读取一致性问题，无法按需强制触发。无法验证 在这里是一个真实、诚实的结果——见下文。

为什么这张表是机器核验的

手工维护的怪癖列表会腐烂。上面的 #4 声明就是证明：它在 2026-08-17 被记录为 成立，并在四天后，即 2026-08-21 被推翻，当时 Instantly 显然在服务端修复了 ?id= 参数。四天并不是一个很长的尾巴——这正是未文档化的 API 在书面假设下可以移动的速度。

npm run verify-gotchas 会针对线上 API 重新运行每个声明的探测，并打印一个五列的表（#、声明、结论、观察结果、最后核验时间）——这是上面三列摘要的超集，带有线上探测的原始证据和运行日期。这与上面的表形状不同；不要期望逐字节匹配。

每个声明还带有一个文档化的预期结论（#1–#3 和 #5 为 成立，#4 为 被推翻，#6–#8 为 无法验证）——即当前文档化的状态，也就是这个 README 今天所说的内容。脚本仅当探测的实际结论确实与该预期发生变化时（例如，文档化的 成立 返回为 被推翻）才会以非零退出，并准确打印出哪个声明发生了漂移以及漂移的方向。重新确认一个已经文档化的 被推翻 声明（如 #4）不是漂移，也不会导致运行失败——只有新的变化才会。

无法验证 是脚本诚实报告的真实结果，而不是它掩盖的失败，并且它永远不会被视为任一方向的漂移。有些声明确实无法通过安全、只读、非破坏性的探测来核验（见上面的 #6–#8）；脚本会如实说明，而不是猜测或静默跳过。#5 是最清晰的案例：其文档化的 成立 来自线上集成测试套件，而不是这个探测，因此探测返回 无法验证（当前不存在草稿活动）会被报告为“无法重新核验”——而不是失败。

INSTANTLY_API_KEY=your-key npm run verify-gotchas

verify-gotchas 是手动运行的，没有接入 CI——请查看 .github/workflows/ci.yml，它只运行 build、typecheck 和 test。这是一个刻意的选择，而不是疏忽：CI 没有线上 API 密钥（脚本在没有密钥时会干净地自我跳过，打印一条消息并以 0 退出——参见 scripts/verify-gotchas.ts 的顶部——所以无论如何它在 CI 中都会是一个静默的空操作），而且这个脚本的存在是为了接触真实账户的读取端点，而仓库的 CI 没有理由无人值守地做这件事。当你想获得最新读取结果时，请在本地针对你自己的账户运行它。

安装

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": ["-y", "instantly-ai-mcp"],
      "env": { "INSTANTLY_API_KEY": "your-v2-api-key" }
    }
  }
}

从 Instantly 仪表板的 设置 → 集成 → API 获取 v2 API 密钥。需要 Node 20+。

安全模型

工具分为三个层级，由环境变量控制。被禁用的层级根本不会注册到 MCP 服务器上——与这个服务器对话的模型根本无法看到或尝试它不被允许使用的工具，这不是一个巧妙的提示词可以绕过的运行时权限检查。

危险层级故意需要两个标志：开启常规写入（上传线索、将地址加入黑名单）永远不会静默地同时启用活动激活、发送或删除。这四个工具还额外带有 MCP 的 destructiveHint: true 注解——这是一个合规客户端可能会据此行动的提示（例如提示用户确认），即使该层级已启用。这是客户端强制执行的行为，不是这个服务器做出的保证：忽略该提示的客户端会在没有任何额外确认步骤的情况下调用该工具。

工具

读取（始终注册）

• list_campaigns —— 列出所有活动，包括草稿，并解码数字状态。

• list_accounts —— 列出已连接的发送邮箱，包含预热分数、状态和每日限额。

• campaign_state —— 通过三个独立端点交叉核验一个活动的状态，并报告它们不一致的地方，而不是选择一个赢家。线索列表读取是分页范围的（一页，限制 100）；满页会如实报告为分页限制，绝不会报告为 Instantly 的不一致。

• list_leads —— 列出活动的线索，通过单数的 campaign 参数过滤，如果任何返回线索自身的 campaign 字段不一致，会发出警告。读取一页（默认限制 100）；结果中的 pageLimited 会告诉你是否可能有更多线索超出该页。

• find_lead —— 通过 search 参数按电子邮件查找单个线索；当 list_leads 看起来不对时，这是正确的第二意见。search 是模糊的，因此只有当行自身的地址与所请求的地址匹配时才会返回该行——近似匹配会报告为 null，绝不会报告为该线索。

• list_replies —— 列出收到的回复，去除引用的线程/签名，并解码兴趣状态。

写入（INSTANTLY_MCP_WRITE=1）

• add_leads —— 向活动上传线索，通过两条独立读取路径的差异（而不是计数）进行验证。对于超过 100 个线索的活动，验证读取也会受到分页限制——结果的 pageLimited 和 note 字段会说明这一点。

• blocklist_address —— 将一个完整的电子邮件地址加入黑名单；在结构上拒绝裸域名。

• update_lead —— 修补线索的字段。

• create_campaign —— 将活动创建为草稿（绝不发送）；在任何网络调用之前验证时区枚举。

• create_webhook —— 创建 webhook 订阅；在任何网络调用之前验证事件类型枚举。

危险（INSTANTLY_MCP_WRITE=1 且 INSTANTLY_MCP_ALLOW_DANGEROUS=1）

• set_campaign_status —— 激活或暂停活动；激活会立即开始发送真实邮件。

• send_reply —— 向线索发送真实的、不可撤回的回复。纯文本会被 HTML 转义并换行以用于 html 正文，而不是原始粘贴；自行传入 html 以覆盖。

• delete_lead —— 永久删除线索。

• delete_campaign —— 永久删除活动及其历史记录。

已知限制

list_replies 会从每条回复中去除引用的原始线程和签名（src/reply-text.ts）。它刻意保持保守：在输入不明确时，它会保留引用，而不是冒险删除真实文本。因此，下面每一个剩余的边缘情况都会以安全的方向失败——引用的线程会保留在返回的文本中，这是噪音，而不是删除一个句子，那是数据丢失：

• 仅指定星期几的归属行，例如 On Tuesday ... wrote:，不包含去除器所需的任何日期/时间信号，因此不会被去除。

• 指定小写发件人且无地址的归属行，例如 ... at 8:22 AM, john wrote:，无法通过发件人形状检查（真实发件人看起来像地址、大写名称或代词），因此不会被去除。

• 完全由签名组成的正文（第一个非空行是 -- ，前面没有任何内容）会整体返回，包括分隔符，而不是被清空。

构建过程中发现的两处过度剥离确实删除了真实的潜在客户文本：以 -- 开头的正文被完全清空，形如 On May 5 reasons you wrote: ... 的文本被误读为引用线程标记而被截断。两者均在首次发布前修复，并已由离线测试套件覆盖（test/reply-text.test.ts，"Fix round 4"）。

目前仍然没有工具能返回回复的原始、未剥离的 body.text。如果来自 list_replies 的回复读起来异常简短，请先在 Instantly 仪表盘中查看，再下结论说潜在客户说的比实际少。

既有成果

现有的包 instantly-mcp（由 bcharleson 开发）覆盖了类似领域，最后发布于 2025-06-17。截至 2026-08-21，其 npm latest 标签指向 1.0.5，而 next 标签对应 3.0.5-1 —— 因此直接运行 npx instantly-mcp 安装的构建版本远比该包自身最新发布的代码要旧（dist 标签在本文撰写后可能发生变化；请重新运行 npm view instantly-mcp dist-tags 查看当前状态）。这是事实陈述，而非贬低：instantly-ai-mcp 是一个独立、无关联的项目，侧重点不同（坑点表格及其自验证），而不是分支或替代品。

测试

fixture 测试套件（npm test）完全离线运行，针对模拟客户端执行，不需要 API 密钥。另一个独立的实时集成套件由 INSTANTLY_LIVE_TEST=1（以及真实的 INSTANTLY_API_KEY）控制，会调用真实 API —— 但它只会创建、读取和删除自己的一次性草稿营销活动（名为 zz-instantly-ai-mcp-throwaway-<timestamp>），绝不会触碰现有的营销活动或线索，也绝不会激活或发送任何内容。当标志或密钥缺失时它会自动跳过，而这种情况在 CI 中始终成立。

许可证

MIT