callrail-mcp 是一个用于 CallRail REST API v3 的 Model Context Protocol（MCP）服务器。将它配置到 Claude Code、Claude Desktop、Cursor 或其他 MCP 客户端后，可以用自然语言询问通话追踪相关的问题。项目兼容 MCP Python SDK 1.x 和 2.x 两个主要版本。
主要用途 该项目面向通话追踪、线索管理、转化调试和代理商成本归因。常见问题示例包括：拉取某客户上周按来源分组的通话、查看本月所有未接来电、跨所有客户查找某号码近 90 天的通话、获取某通话的通话记录；按客户拆解 CallRail 账单、找出本周期分钟数消耗最大的客户；检查某通话为何未在 Google Ads 中转化、判断 58 秒通话是否符合 Google Ads 转化条件；查看某人所有通话、表单和短信记录，给短信线索打标签并添加备注；以及给通话打标签、在指定区号开通新的 Google Ads 呼叫扩展追踪器（需要 confirm_billing=True，约每月 3 美元）。
主要能力 共 57 个工具，覆盖约 95% 的 CallRail REST API v3 接口，包括：读取工具、写入工具、追踪器开通、代理商聚合、账户管理、通知、集成发现、外呼、离线线索回填、线索与跨渠道时间线、短信线索管理以及服务端分析。所有工具均可选传 account_id；若省略，会自动解析首个可访问账户并缓存在当前进程。可通过设置 CALLRAIL_ACCOUNT_ID 跳过查找或固定账户。大多数工具接受 company_id 以筛选单个客户。
在过滤通话方面，CallRail 的 GET /calls.json 支持 answer_status（answered、missed、voicemail），但没有 answered 或 source 参数。该服务器 v1.2.0 之后将 answer_status 作为服务端过滤，answered 作为已弃用别名转换为 answer_status，source 则在客户端应用并在响应中返回 source_filter 说明匹配内容；来源细分建议使用 call_stats(group_by="source")。另外，CallRail 将语音邮件计为已接听，自 v1.3.0 起，call_summary、spam_detector、call_eligibility_check 和 bulk_update_calls 仅在真人接听（answered 且非 voicemail）时视为已接听，并单独报告语音邮件；answer_status=missed 包含语音邮件。无日期窗口时，CallRail 默认返回最近范围（含今天的前 7 天）而非全部时间。带窗口的工具支持 IANA 时区，usage_summary / compare_periods 会自动转发账户时区。通信记录保留 25 个月，超出范围的窗口会返回错误要求缩小范围。
验证严格，涵盖电话号码格式、区号（^\d{3}$）、会话池大小（CallRail 的 4 到 50 范围）、名称、耳语和问候长度上限，以及 12 值的来源类型枚举。
字段选择 CallRail API 默认返回精简字段。可通过 fields 参数在 list_calls、get_call 或 list_form_submissions 上请求更多字段，也支持按名称获取会话智能和归因字段，如 lead_status、sentiment、call_summary、call_highlights、keywords_spotted、transcription、conversational_transcript、speaker_percent、milestones、timeline_url、msclkid、prior_calls、total_calls、person_id 等，完整字段目录参见 CallRail API 文档。
工具注解 每个工具声明 MCP 工具注解：33 个读取工具带 readOnlyHint，删除和批量写入带 destructiveHint，更新带 idempotentHint，create_outbound_call 因触达电话网络带 openWorldHint。支持注解的客户端可自动批准读取、写入前询问。
使用方式 从源码安装（最新未发布版本）：可在 CallRail 账户的 Settings > API Keys 获取 API 密钥，需要 Account Admin 权限才能创建。提供密钥有两种方式：环境变量（多数场景推荐）或密钥文件，也可用 CALLRAIL_API_KEY_FILE=/path/to/key.txt 覆盖。可选固定账户：每个工具每进程通过一次 GET /a.json 解析账户 id 并缓存，设置 CALLRAIL_ACCOUNT_ID 可跳过查找，或在密钥可访问多个账户时固定一个。
配置 MCP 客户端：Claude Code / Claude Desktop（~/.claude.json 或 claude_desktop_config.json）中，若通过 pipx 安装则 callrail-mcp 自动在 PATH 中，否则将 command 指向可执行文件的完整路径。Cursor 及其他客户端：服务器使用标准 MCP stdio，任何支持 stdio MCP 服务器的客户端均可将 callrail-mcp 作为命令运行。
直接运行服务器可用于调试或验证密钥：服务器等待 stdin 上的 JSON-RPC 消息，按 Ctrl-C 退出。也可在不运行 MCP 循环的情况下冒烟测试 API 密钥。
作为 Python 库使用 CallRailClient 也可作为库使用。paginate() 接受可选的 stats 字典，报告 pages_fetched、items_yielded、total_records 和 truncated，便于区分被截断的结果与完整结果。
与官方 MCP 服务器的对比 CallRail 官方提供托管 MCP 服务器（文档见 apidocs.callrail.com），使用 OAuth 2.0，约 30 个工具，服务器 URL 由 CallRail 账户团队提供，适合全托管远程服务器。本项目与官方服务器使用相同的底层 REST API v3，但侧重代理商工具、安全防护，以及对照 CallRail 文档和实际响应检查的请求契约。另有社区 TypeScript 服务器 @kanopi/callrail-mcp（npm，34 个工具，stdio，API 密钥认证）。
有意未实现的范围 以下能力因设计原因不在本 MCP 中。受 CallRail 账户权限限制（返回 403）：发送 SMS/MMS（POST /text-messages.json）需要 A2P/TCR 短信注册，CallRail 对出站短信强制执行 TCPA 合规关键词（STOP、CANCEL、UNSUBSCRIBE），MMS 支持于 2026-05-05 由 CallRail 添加；Webhook 集成创建、更新、删除（POST /integrations.json 且 type=Webhook）需要 Integration-Admin 权限；出站主叫 ID（/caller_ids.json CRUD）文档有记载但标准账户返回 403；消息流（/message-flows.json CRUD，短信自动回复流）文档有记载但返回 403；集成过滤器（/integration_triggers.json CRUD）文档有记载但返回 403。表单提交端点在某账户下没有任何公司启用 Form Tracking 时返回 403，这属于账户状态而非权限，启用 Form Tracking 后端点即可用，工具会在错误中说明。
CallRail REST API 未暴露的能力（仅通过 Web UI 管理）：号码（账户级号码所有权、携号转网和转移）、呼叫流（IVR 构建器和呼叫路由树配置）、自定义字段 CRUD（自定义数据列可作为通话和表单响应的一部分读取，但架构管理端点未暴露）、Do Not Call 列表（DNC 号码管理）。
可读但尚未发布的功能：标准账户可读但被认为价值较低，包括 summary_emails CRUD、companies/bulk_update.json（仅外部表单捕获）和 form_submissions/ignored_fields.json。
限制与配额 CallRail 文档默认限制为一般 API 请求每小时 1,000 次、每天 10,000 次；短信发送另有每小时 150 次、每天 1,000 次预算；外呼每小时 100 次、每天 2,000 次。客户端使用 Retry-After 头重试 429 响应，对 5xx 响应仅对幂等方法（GET、PUT、DELETE、HEAD、OPTIONS）使用指数退避重试。POST 在 5xx 时永不重试，因此丢失响应不会创建重复追踪器。大量分页建议使用内置 paginate() 辅助函数。
其他信息 项目采用 MIT 许可证，版权所有 (c) 2026 Steve Japalucci / Pittsburgh Digital Marketing Agency。该项目是独立开源集成，与 CallRail 无隶属、认可或官方支持关系。"CallRail" 是 CallRail, Inc. 的商标。开发流程、API 怪癖和代码库约定见 DEVELOPMENT.md，贡献指南见 CONTRIBUTING.md，安全问题按 SECURITY.md 私下报告。
