Ballast

Ballast MCP 服务

Model Context Protocol (MCP) 的官方服务实现，适用于 Ballast — 将 AI Agent 接入 Ballast，以管理冷邮件营销活动、送达率预热、潜在客户列表和收件箱回复。

此代码库包含独立的 MCP 服务包，通过标准输入/输出（stdio）在本地运行，并将 AI 助手（Claude Desktop、Cursor、Claude Code、Zed 等）连接到你的 Ballast 工作区。

---

功能

• 送达率与 DNS 诊断：检查辅助域名的 SPF、DKIM、DMARC 对齐、MX 配置和黑名单状态。
• 营销活动与序列管理：构建多步骤外发序列、设置 A/B 变体、配置发送延迟，并核对启动检查清单。
• 自动退信熔断器：监控营销活动的投递率，并在退信率超过阈值时暂停发送。
• 统一收件箱（Unibox）：阅读并总结客户邮件对话、检查情感分类，并起草由人工确认的回复。
• 默认安全：破坏性操作（启动营销活动、发送邮件、删除数据）需要通过 10 分钟有效期的 HMAC 令牌进行明确的两步确认。

---

安装与设置

要求

• Node.js >= 18.0.0
• Ballast 工作区 API 密钥，可从 Settings > API Keys 获取（以 bl_ 开头）。

通过 npx 运行（推荐）

你可以直接运行服务，无需手动安装：

BALLAST_API_KEY="bl_your_key_here" npx -y ballast-mcp

从源代码安装

git clone https://github.com/useballast/ballast-mcp.git
cd ballast-mcp
npm install
npm start

---

客户端配置

Claude Desktop

将 Ballast 添加到你的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": ["-y", "ballast-mcp"],
      "env": {
        "BALLAST_API_KEY": "bl_your_api_key_here"
      }
    }
  }
}

---

Cursor

添加到 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json）：

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": ["-y", "ballast-mcp"],
      "env": {
        "BALLAST_API_KEY": "bl_your_api_key_here"
      }
    }
  }
}

---

Claude Code

claude mcp add --transport stdio ballast -- npx -y ballast-mcp --key=bl_your_api_key_here

（注意：对于直接支持远程 Streamable HTTP 的客户端，也可以使用 --transport http ballast https://ballast.to/api/mcp --header "Authorization: Bearer bl_..."）

---

工具参考

该服务实现了 30 个核心工具，按功能领域组织：

工具	类别	描述
whoami	工作区	获取已认证用户、当前工作区和权限角色。
get_overview	工作区	汇总整个工作区所有营销活动的数据与趋势（发送量、回复量、情绪、退信量）。
get_billing	工作区	套餐详情、发送额度、专用 IP 和使用限额。
check_domain	域名	对任意域名进行实时 DNS 和送达能力诊断，无需添加该域名。
list_domains	域名	列出已连接的发送域名及其送达能力评分和验证状态。
add_domain	域名	将新的发送域名连接并注册到工作区。
list_mailboxes	邮箱	列出已连接的 Google Workspace 和 Microsoft 365 邮箱及其每日限额。
add_mailbox	邮箱	连接外部邮箱以进行主动外联。
list_leads	潜在客户	搜索并筛选工作区中的联系人。
import_leads	潜在客户	导入潜在客户联系人，并设置自定义变量和标签。
list_lead_lists	潜在客户	列出整理好的潜在客户细分及成员数量。
add_suppressions	潜在客户	将电子邮件地址或根域名添加到整个工作区的禁止联系列表。
list_campaigns	营销活动	列出外联序列及其发送计划和状态。
create_campaign	营销活动	创建新的冷邮件营销活动。
get_campaign	营销活动	获取营销活动设置、步骤变体和已分配邮箱。
update_campaign	营销活动	更新营销活动计划、每日配额或跟踪设置。
set_sequence	营销活动	配置序列步骤、延迟时间、主题行和正文文案。
write_sequence	营销活动	使用 AI 生成或润色多步骤序列文案。
add_leads_to_campaign	营销活动	将潜在客户细分加入正在进行的序列。
preview_campaign	营销活动	预览各邮箱的潜在客户发送分配情况和首次发送时间。
get_launch_checklist	营销活动	在启动前检查域名对齐情况、发件人预热情况和潜在客户数据质量。
launch_campaign	营销活动	启动序列发送（需要确认令牌）。
pause_campaign	营销活动	立即暂停营销活动的发送。
get_campaign_stats	营销活动	获取某个或所有营销活动的每日电子邮件指标时间序列。
get_campaign_analytics	营销活动	按电子邮件服务提供商（Google、Microsoft）、邮箱和情绪细分查看详细表现。
get_unibox_filters	统一收件箱	获取统一收件箱筛选预设和标签数量。
list_threads	统一收件箱	列出收到的收件人回复和对话线程。
get_thread	统一收件箱	查看完整的线程消息历史、邮件头信息和潜在客户详情。
send_reply	统一收件箱	使用线程所分配的邮箱发送电子邮件回复（需要确认令牌）。
label_thread	统一收件箱	应用情绪标签（感兴趣、已预约会议、不感兴趣、外出）。

---

安全：两步确认

为防止意外批量发送或删除数据：

1. 调用 launch_campaign、send_reply 或删除工具时，如果未提供 confirm_token，服务会生成一次试运行预览，说明确切结果（例如 “将通过 6 个邮箱发送 320 封电子邮件”），并签发一个 HMAC 令牌。
2. AI 会向用户展示该预览。
3. 只有用户批准且 AI 传入 confirm_token 后，操作才会执行。

---

开发

git clone https://github.com/useballast/ballast-mcp.git
cd ballast-mcp
npm install
npm test # or npm start

许可证

MIT © Ballast