CallHub MCP Server 是一个 MCP（Model Context Protocol）服务器，将 CallHub 的 REST API 暴露为工具，让任何兼容 MCP 的 AI 助手能够通过自然语言管理 CallHub 资源。CallHub 本身是一个面向倡导组织、工会、政治组织、非营利机构和组织团队的呼叫与短信平台，提供语音广播、呼叫中心/电话银行、P2P 和批量短信以及联系人管理等功能。该服务器主要封装公开端点，也包含一些内部/扩展端点（每个工具在参考文档中均有标记）。
主要能力 服务器注册了约 135 个工具，覆盖 CallHub 的各个资源领域：
- 联系人：创建、获取、更新、删除，以及 listContacts、searchContacts、bulkCreateContacts、addContactNotes、自定义字段和标签。
- 联系人列表（又称电话簿）：创建、获取、更新、删除、列出，添加/移除联系人，计数。
- 代理与团队：创建、获取、列出代理，实时代理，团队 CRUD 与成员管理，激活 URL 导出。
- 活动：呼叫中心、语音广播、文本广播、P2P 和关系组织活动的创建、获取、列出、更新状态、复制、删除、分配代理。
- DNC 与抑制：DNC 列表和联系人，addToDnc / removeFromDnc，addToSuppressionList。
- 号码：租用、自动租用短信号码，列出已租用/已验证号码，重新验证。
- 媒体、Webhook、报告：媒体列表/上传，Webhook CRUD，活动统计，信用使用，导出作业轮询，短链接统计，shareCredits。 工具名称遵循 CallHub 的产品词汇（如 createContactList、createVoiceBroadcastCampaign、createTextBroadcast、addTagsToContact）。旧版本名称（如 createPhonebook、createVbCampaign、createSmsBroadcast 等）仍作为隐藏别名可用，因此已保存的流程可继续运行；新工作应使用规范名称。
使用方式 该服务器通过 stdio 在本地运行，使用 API 密钥向 CallHub 认证。它可与任何 MCP 客户端配合使用，包括 Claude Desktop、Cursor、Windsurf、Cline、Continue、OpenAI Codex、Gemini CLI 等，并作为一键 .mcpb 包提供给 Claude Desktop。
安装（Claude Desktop）： 从 dist/ 或最新发布版下载对应平台的包：macOS (Apple Silicon): callhub-macos-arm64.mcpb；macOS (Intel): callhub-macos-x64.mcpb；Windows (x64): callhub-win-x64.mcpb；Linux (x64): callhub-linux-x64.mcpb。打开 Claude Desktop → 设置 → 扩展，将文件拖入（或双击）。输入扩展设置（见配置）。启用扩展。CallHub 工具即可使用。要求：系统上可用 Python 3.10–3.14。每个包为该范围内的每个 Python 版本内置了依赖，因此任一版本均可工作。
安装（其他 MCP 客户端）： 任何能启动本地命令的 MCP 客户端都可以运行此服务器。克隆并安装依赖，然后将客户端指向 src/server.py。然后向客户端注册服务器。大多数客户端使用 mcpServers JSON 块——通过环境变量传递凭据。客户端特定快速命令：
- Gemini CLI：gemini mcp add callhub python3 /absolute/path/to/callhub-mcp/src/server.py（然后设置 CALLHUB_* 环境变量）。
- OpenAI Codex：在 ~/.codex/config.toml 中添加 [mcp_servers.callhub] 块，command = "python3"，args = ["/absolute/path/.../src/server.py"]。
- Cursor / Windsurf / Cline / Continue：将上述 mcpServers 块添加到客户端的 MCP 配置文件中。 如果服务器的依赖不在系统 Python 上，请使用 venv 的 Python（.venv/bin/python3）作为命令。
配置： 需要两个值，均来自 CallHub 仪表板中的 设置 → 账户 → API 密钥：
- API Key——那里显示的密钥。
- API Domain——那里显示的基础 URL，因区域而异（例如 https://api-na1.callhub.io）。 在 Claude Desktop 中，这些是扩展设置。对于其他客户端，将它们设置为 CALLHUB_API_KEY 和 CALLHUB_BASE_URL 环境变量。 媒体上传（可选）：除非将 uploadMediaFile 指向已批准的文件夹（媒体上传目录设置或 CALLHUB_MEDIA_DIR 环境变量），否则该工具被禁用。该工具随后只能从该文件夹内读取文件（此外还有媒体扩展名检查），因此它永远无法读取主机上的任意文件。
多账户： 配置的密钥是默认账户。要使用更多账户，请让助手按名称配置一个（configureAccount 工具），然后在请求中按名称引用它——例如，“列出我个人账户中的团队。”未指定账户的请求使用 default。其他账户的凭据存储在本地 .env 文件中，使用模式 CALLHUB_<ACCOUNT>_API_KEY / _BASE_URL / _USERNAME。
适用场景 适用于需要通过 AI 助手以自然语言管理 CallHub 资源的场景，例如批量创建联系人、管理活动、分配代理、处理 DNC 列表、租用号码、上传媒体、配置 Webhook 和获取报告等。特别适合倡导组织、工会、政治组织、非营利机构和组织团队等使用 CallHub 进行呼叫和短信工作的用户。
限制与注意事项
- CallHub API 有速率限制；服务器会暴露 429 响应而不是掩盖它们。特别是 searchContacts 限制为大约每秒一次请求——优先使用单次 searchContacts 调用，而不是快速分页 listContacts。对于批量工作，使用批量端点（bulkCreateContacts）而不是许多单次调用。
- 新创建的代理处于待处理状态，必须验证其电子邮件后才会出现在 listAgents 中。通过激活导出工作流管理它们：exportAgentActivationUrls（或 getAgentActivationExportUrl）获取导出；从 CallHub UI 下载激活 CSV；processAgentActivationCsv（或 processUploadedActivationCsv）读取它。早期版本捆绑了 Selenium/Chrome 流程自动设置代理密码，但为了保持服务器轻量和可靠已移除——请将激活 URL 分发给代理，或在 CallHub UI 中激活它们。
- 构建会生成针对所构建平台的 callhub.mcpb（某些依赖附带编译的 wheel，因此包是特定于操作系统/架构的）。build-all.sh 交叉下载平台 wheel（无需执行）并为每个平台打包一个包，每个包包含所有支持的 Python 版本的编译依赖。构建要求：python3（3.10+）和 mcpb CLI（通过 npx @anthropic-ai/mcpb 调用，因此构建时需要 Node.js）。
- 仓库结构：manifest.json——MCPB 扩展清单（服务器入口、user_config）；src/server.py——注册每个工具并启动 MCP 服务器（stdio）；src/callhub/——API 客户端、认证以及每个资源一个模块；docs/API_REFERENCE.md——工具到端点的参考；build.sh——可重现的包构建。
- API 密钥通过扩展设置（Claude Desktop）或环境变量提供，不会提交到此仓库。建议使用范围最小权限的 API 密钥。
