callrail-mcp

<!-- mcp-name: io.github.pghdma/callrail-mcp --> # CallRail-MCP [](https://pypi.org/project/callrail-mcp/) [](https://pypi.org/project/callrail-mcp/) [](https://github.com/pghdma/callrail-mcp/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io/) [](https://codeguilds.dev/packages/callrail-mcp) 一个 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，暴露 [CallRail REST API v3](https://apidocs.callrail.com/) 给任何兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）。 由 **[Steve Japalucci](https://github.com/pghdma)** 创建 — [匹兹堡数字营销机构（PGHDMA）](https://pghdma.com) 的创始人。 ## 你可以让 Claude 做的事情 安装完成后，任何具有 MCP 意识的助手都可以回答以下问题： **报告** - *"提取上周艾伦建筑公司的通话记录，按来源分组"* - *"显示本月 Google Ads 中所有未接通的通话"* - *"查找过去 90 天内所有来自 412-555-1234 的通话，涵盖所有客户"* - *"获取通话 CAL019abc... 的转录记录"* **代理成本归因** *(v0.4 新增)* - *"为什么我的 CallRail 账单是 174 美元？按客户分摊"* - *"哪个客户是本周期内最大的分钟使用者？"* **转化调试** *(v0.4 新增)* - *"为什么这个通话在 Google Ads 中没有转化为有效线索？CAL019..."* - *"这个 58 秒的通话是否有资格计为 Google Ads 转化？"* **标签 + 跟踪器管理** - *"将此通话标记为 '潜在客户' 并添加备注"* - *"为区域代码 412 中的文艺复兴提供新的 Google Ads 通话扩展跟踪器"*(需要 `confirm_billing=True` — 费用约为 3 美元/月)* ## 安装 ```bash # 推荐：使用 pipx 进行隔离 CLI 安装 pipx install callrail-mcp # 或使用 pip pip install callrail-mcp ``` 要从源代码安装（最新未发布版本）： ```bash pipx install git+https://github.com/pghdma/callrail-mcp.git ``` ## 认证 在 CallRail 账户的 **设置 → API 密钥** 中获取 API 密钥。您需要账户管理员权限才能创建 API 密钥。 通过以下两种方式之一提供 API 密钥： ### 选项 1：环境变量（推荐大多数设置） ```bash export CALLRAIL_API_KEY="your_key_here" ``` ### 选项 2：密钥文件 ```bash mkdir -p ~/.config/callrail echo "your_key_here" > ~/.config/callrail/api-key.txt chmod 600 ~/.config/callrail/api-key.txt ``` 或使用 `CALLRAIL_API_KEY_FILE=/path/to/key.txt` 覆盖。 ## 配置你的 MCP 客户端 ### Claude Code / Claude Desktop (`~/.claude.json` 或 `claude_desktop_config.json`) ```json { "mcpServers": { "callrail": { "command": "callrail-mcp", "env": { "CALLRAIL_API_KEY": "your_key_here" } } } } ``` 如果您通过 pipx 安装，`callrail-mcp` 将自动位于您的 PATH 中。否则，请将 `command` 指向可执行文件的完整路径。 ### Cursor / 其他客户端 服务器使用标准 MCP stdio 协议。任何支持 stdio MCP 服务器的客户端都可以使用 — 只需将 `callrail-mcp` 作为命令运行。 ## 可用工具 **共 59 种工具** — 大约 95% 的 CallRail REST API v3 接口。读取工具、写入工具、跟踪器配置、代理聚合、帐户管理（公司/用户 CRUD）、通知、集成发现、出站通话、离线线索回填（通过 `create_form_submission`），以及（v1.1 新增）线索、SMS 线程管理、服务器端分析和每通话页面浏览量。 ### 读取工具 | 工具 | 目的 | |---|---| | `list_accounts` | 列出可访问的 CallRail 账户 | | `list_companies` | 列出某个账户下的公司（客户）。可选 `status="active"` 过滤器 | | `list_trackers` | 列出跟踪电话号码及其源映射。可选 `status="active"` 过滤器 | | `get_tracker` | 获取某个跟踪器的完整详细信息 | | `list_calls` | 分页通话列表 — 按公司/日期/来源/是否接通过滤 | | `get_call` | 获取特定通话的完整详细信息 | | `call_summary` | 获取某个时间窗口的汇总统计数据（总数、接通数、按来源、时长） | | `list_form_submissions` | CallRail 表单跟踪提交记录 | | `list_text_messages` | SMS 对话记录 | | `list_users` | 账户用户列表 | | `get_call_recording` | 通话录音 URL（如果启用录音） | | `get_call_transcript` | 会话智能转录记录 | | `search_calls_by_number` | 按电话号码查找通话记录，涵盖某个时间窗口 | | `list_tags` | 列出账户或过滤到某个公司的标签 | ### 写入工具 *(v0.2+)* | 工具 | 目的 | |---|---| | `update_call` | 更新备注、标签、垃圾邮件标志、客户姓名、线索状态 | | `add_call_tags` / `remove_call_tags` | 添加/删除标签（保留现有标签） | | `update_form_submission` | 与 `update_call` 相同的字段表面，**另外** `value`（数字类型，支持表单提交，但不支持通话 — CallRail 返回 500） | | `create_tag` / `update_tag` / `delete_tag` | 完整的公司级标签分类 CRUD | ### 跟踪器配置 *(v0.3+)* | 工具 | 目的 | |---|---| | `create_tracker` | 配置新的跟踪号码。**需要 `confirm_billing=True`** 作为安全防护措施，防止意外 AI 配置 | | `update_tracker` | 更新可变设置：名称、目的地、耳语、问候、SMS | | `delete_tracker` | 软删除跟踪器（释放电话号码，保留历史记录） | ### 账户管理 *(v0.6+)* | 工具 | 目的 | |---|---| | `get_company` / `create_company` / `update_company` / `delete_company` | 完整的公司（客户）CRUD。免费 — CallRail 按号码计费，而非按公司计费。软删除语义 | | `get_user` / `create_user` / `update_user` / `delete_user` | 完整用户 CRUD。`create_user` 通过电子邮件邀请；常见角色：管理员 / 经理 / 报告 / 分析师 | | `get_tag` | 单个标签详情（完成标签 CRUD） | | `get_form_submission` | 单个表单提交详情（仅限列表和更新） | | `get_text_message` | 具有所有消息的单个 SMS 对话详情 | | `create_form_submission` *(v0.7)* | 手动创建表单提交（回填走访 / 纸质表单 / 离线线索） | ### 通知 + 集成 *(v0.7+)* | 工具 | 目的 | |---|---| | `list_notifications` / `create_notification` / `update_notification` / `delete_notification` | 完整用户警报规则 CRUD（哪些用户在哪些通话/文本/表单事件上收到通知） | | `list_integrations(company_id)` / `get_integration` | 发现附加到某个公司的 GMB / Google Ads / Facebook / Slack / Webhook 集成 | | `list_webhooks` / `get_webhook` | 读取 Webhook 订阅（写入 CRUD 被 CallRail 账户权限阻止 — 见下文“超出范围”） | ### 出站通话 *(v0.7+)* | 工具 | 目的 | |---|---| | `create_outbound_call` | 拨打出站通话（CallRail 先拨打您的跟踪器，然后桥接到接收者）。**需要 `confirm_dialing=True`** 作为安全防护措施，防止意外拨打真实电话，产生费用并具有法律影响 | 验证很严格：电话号码格式、区号（`^\d{3}$`）、`pool_size` ∈ [1, 50]（防止意外计费账单的安全上限），名称/耳语/问候长度上限，源类型枚举（12 个值：文档中列出的 10 个值，加上 `facebook_all` / `bing_all`，已在生产环境中验证，但仍未出现在文档中）。标签颜色根据完整的 24 种颜色集进行验证。 ### 线索和服务器端分析 *(v1.1+)* | 工具 | 目的 | |---|---| | `list_leads` / `get_lead_timeline` | CallRail 的去重人员记录 + 完整的跨渠道历史记录（通话 + 表单 + 文本）每个线索，附带首次/最后接触归因 | | `list_sms_threads` / `get_sms_thread` / `update_sms_thread` | SMS 线程线索管理 — 为线索添加标签/备注/资格认定，像通话一样（`update_sms_thread` 弥补了文本写入的空白） | | `call_stats` | 服务器端通话聚合（`/calls/summary.json`）— 按来源/关键词/活动/引荐者/着陆页/公司分组汇总，**一次请求** 而不是分页每个通话 | | `call_timeseries` | 每天的通话量时间序列趋势线（`/calls/timeseries.json`） | | `form_stats` | 服务器端表单提交总数 | | `get_call_page_views` | 通话背后的访问者页面浏览记录 — 与 `call_eligibility_check` 配合使用进行转化调试 | ### 代理聚合 *(v0.4+)* | 工具 | 目的 | |---|---| | `usage_summary` | 某个周期的公司成本归因明细。返回已使用的分钟数、活动号码、预估成本份额 — 按最大成本驱动因素排序。有助于回答“哪个客户正在消耗我的 CallRail 预算” | | `call_eligibility_check` | 审核特定通话是否有资格计为 Google Ads 转化。检查 `gclid` 存在、接通状态、时长与 Google 的阈值（默认 60 秒），以及来源。有助于回答“我的转化去哪了”调试问题 | | `compare_periods` *(v0.5)* | 比较当前 N 天窗口与之前的 N 天窗口。公司分钟/通话增量 + 最大变动。提前发现流量趋势 | | `bulk_update_calls` *(v0.5)* | 对匹配过滤器的每个通话应用单个更新（标签/备注/线索状态/垃圾邮件）。默认 `dry_run=True`；在 500 容量时出现截断 | | `spam_detector` *(v0.5)* | 启发式标记可能为垃圾邮件的通话（短时长、无人接听、重复呼叫者模式）。可选 `auto_tag=True` 添加 `auto_detected_spam` 标签。故意不设置 `spam=True`（这会从默认 GET 中隐藏通话） | 所有工具都可选地接受 `account_id` — 如果省略，则自动解析为第一个可访问的账户。大多数工具都接受 `company_id` 以过滤到单个客户。 ## 与 CallRail 官方 MCP 服务器的比较 CallRail 现提供官方托管的 MCP 服务器（在 [apidocs.callrail.com](https://apidocs.callrail.com/#mcp) 中记录）— OAuth 2.0，约 30 种工具，服务器 URL 由您的 CallRail 账户团队提供。 这是一个很好的选择，如果您想要一个完全托管的远程服务器。 本项目仍然有意保持不同： | | CallRail-MCP（本项目） | 官方 CallRail MCP | |---|---|---| | 安装 | `pip install callrail-mcp` — 2 分钟内运行 | URL 由您的 CallRail 账户团队提供 | | 托管 | 本地 stdio（您的 API 密钥从未离开您的机器） | 托管远程（OAuth） | | 工具 | 59 | 约 30 | | 代理工具 | `usage_summary` 成本归因，`compare_periods`，`spam_detector`，`bulk_update_calls`，`call_eligibility_check` | 未提供 | | 安全防护 | `confirm_billing` / `confirm_dialing` / `dry_run` 默认值，严格的输入验证 | — | | 源代码 | MIT，开源，可审计 | 封闭 | 两者都使用相同的底层 REST API v3。如果您是代理商，运行 Claude 以对抗多个客户端账户，并希望进行成本归因和批量工作流程，则此项目正是为您而建。 ## 超出范围（故意未实现） 以下 CallRail 功能**未在此 MCP 中实现**，这是有意为之。 如果您有支持它们的账户，请欢迎提交 PR — 或提出问题，我们将优先处理。 ### 被 CallRail 账户权限阻止（返回 403） 这些端点存在但需要账户升级/额外权限，而我们的标准 CallRail 账户没有这些权限。验证于 2026-04-24 生效： - **发送 SMS** (`POST /text-messages.json`) — 需要 A2P SMS 注册/专用 SMS API 权限。CallRail 在出站 SMS 消息上强制执行 TCPA 合规性关键词（STOP / CANCEL / UNSUBSCRIBE）。 - **创建/更新/删除 Webhook 集成** (`POST /integrations.json`，类型=Webhook) — 需要集成管理员权限。CallRail 通过集成框架管理 Webhook，而不是独立的端点。 ### CallRail 标准计划中不可用的 API 接口（仅限 UI） 这些 API 接口没有对应的 API 接口 — 仅在 CallRail Web UI 中可管理： - **出站 Caller IDs** — 出站呼叫者 ID 验证流程。 - **号码** — 账户级号码所有权、移植、转移。 - **通话流程** — IVR 构建器/通话路由树配置。 - **自定义字段 CRUD** — 自定义数据列作为通话/表单响应的一部分可读，但架构管理端点未公开。 - **禁止呼叫列表** — 禁止呼叫号码管理。 ### 如果/当 如果 CallRail 升级 API 或用户升级账户权限，可以在不进行重大更改的情况下添加上述内容 — 我们只需将它们公开为新的 MCP 工具。 ### 丰富的字段选择 CallRail API 返回精简的默认有效负载。在 `list_calls` / `get_call` / `list_form_submissions` 中请求更多字段，请使用 `fields` 参数： ``` fields=company_name,source_name,keywords,landing_page_url,device,first_call,value,tags,note,gclid,fbclid,utm_source,utm_medium,utm_campaign,utm_content,utm_term,referrer_domain ``` 参见 [CallRail API 文档](https://apidocs.callrail.com/) 以获取每个资源的完整字段目录。 ## 示例 ### Claude Code ``` > 列出我们 CallRail 账户下的公司。 (Claude 调用 list_companies → 返回具有 ID 和主要号码的客户端) > 拉取今天的艾伦建筑公司通话记录 — 包括来源和关键词。 (Claude 调用 list_calls，带有 company_id、days=1、fields="source,keywords,landing_page_url") > 为什么这个月的 CallRail 账单是 174 美元？按客户分摊。 (Claude 调用 usage_summary → 返回每个客户的成本份额，按最大用户排序) > 为什么这个通话在 Google Ads 中没有显示为转化？CAL019dbf79... (Claude 调用 call_eligibility_check → 返回 gclid/时长/接通检查 + 目标原因，如“时长 58 秒低于 Google Ads 最低时长（60 秒）”) > 为艾伦建筑公司在 412 地区配置一个新的 Google-Ads-Call-Extension 跟踪器。 (Claude 调用 create_tracker — 除非您还传递 confirm_billing=True，否则拒绝 因为这会产生约 3 美元/月的费用) ``` ### 直接 Python 使用 `CallRailClient` 也可用作库： ```python from callrail_mcp.client import CallRailClient cr = CallRailClient() # 获取 CALLRAIL_API_KEY aid = cr.resolve_account_id() for call in cr.paginate(f"a/{aid}/calls.json", {"per_page": 250}, items_key="calls"): print(call["id"], call.get("source"), call.get("customer_name")) ``` ## 直接运行服务器 用于调试或验证您的密钥是否有效： ```bash python -m callrail_mcp ``` 服务器使用 MCP stdio 协议。它将等待 stdin 上的 JSON-RPC 消息。按 Ctrl-C 退出。 要验证 API 密钥而不运行 MCP 循环： ```python python -c "from callrail_mcp.client import CallRailClient; c=CallRailClient(); print(c.get('a.json'))" ``` ## 速率限制 CallRail 允许每个 API 密钥每分钟 60 个请求。客户端使用 `Retry-After` 头重试 429 响应，并使用指数退火（默认最多 3 次重试）重试 5xx 响应。对于重分页，请优先使用内置的 `paginate()` 帮助程序，它默认使用 `per_page=100`。 ## 开发 ```bash git clone https://github.com/pghdma/callrail-mcp cd callrail-mcp python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest ``` ## 贡献 欢迎贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发设置、测试约定和发布流程。 请通过 [GitHub Issues](https://github.com/pghdma/callrail-mcp/issues) 提交问题，并遵循 [Code of Conduct](CODE_OF_CONDUCT.md)。 ## 安全 如果您发现安全漏洞，请按照 [SECURITY.md](SECURITY.md) 私密报告，而不是公开问题。 ## 作者 **[Steve Japalucci](https://github.com/pghdma)** — [匹兹堡数字营销机构](https://pghdma.com) 创始人。联系方式：[s@pghdma.com](mailto:s@pghdma.com)。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。版权所有 © 2026 Steve Japalucci / 匹兹堡数字营销机构。 ## 免责声明 本项目是一个独立的开源集成，与 CallRail 无关，不受 CallRail 支持或官方认可。“CallRail”是 CallRail, Inc. 的商标。所有产品名称、徽标和品牌均为其各自所有者的财产。