CallRail MCP

callrail-mcp

一个用于 CallRail REST API v3 的 Model Context Protocol 服务。让 Claude Code、Claude Desktop、Cursor 或任何其他 MCP 客户端连接到它，就可以用日常语言询问通话追踪情况。

我是 Steve Japalucci。我经营着 Pittsburgh Digital Marketing Agency (PGHDMA)，并为自己的客户项目构建了这个工具。我管理的每个客户都会产生 CallRail 追踪号码和通话分钟费用，而我早已厌倦了在报告中反复点击，只为回答“这个月哪个客户用掉了我的分钟数”之类的问题。现在，我直接问 Claude。

兼容 MCP Python SDK 的两个主要版本（1.x 和 2.x）。

我用它做什么

以下是我每周都会问它的一些问题：

报告

• “调取 Alan Construction 上周的通话，并按来源分组”
• “显示我本月的所有未接来电”
• “查找过去 90 天内所有客户中来自 412-555-1234 的通话”
• “获取通话 CAL019abc... 的转录文本”

代理机构成本归属

• “为什么我的 CallRail 账单是 $174？按客户拆分”
• “本计费周期内哪个客户使用的分钟数最多？”

转化问题排查

• “为什么这通电话没有在 Google Ads 中转化？CAL019...”
• “这通 58 秒的电话符合计为 Google Ads 转化的条件吗？”

潜在客户管理

• “显示这个人做过的所有事情：通话、表单、短信”
• “将这条 SMS 对话标记为合格潜在客户并添加备注”

标签和追踪器管理

• “将这通电话标记为‘潜在客户’并添加备注”
• “为 Renaissance 在区号 412 配置一个新的 Google Ads 来电扩展追踪器”（需要设置 confirm_billing=True，费用约为每月 $3）

安装

# Recommended: pipx for an isolated CLI install
pipx install callrail-mcp

# Or with pip
pip install callrail-mcp

从源代码安装（最新未发布版本）：

pipx install git+https://github.com/pghdma/callrail-mcp.git

身份验证

在 CallRail 账户的 Settings > API Keys 中获取 API 密钥。创建密钥需要账户管理员权限。

可通过以下两种方式之一提供密钥：

选项 1：环境变量（推荐用于大多数配置）

export CALLRAIL_API_KEY="your_key_here"

选项 2：密钥文件

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 覆盖。

可选：固定账户

每个工具都会在每个进程中通过一次 GET /a.json 获取账户 ID 并缓存。设置 CALLRAIL_ACCOUNT_ID 可跳过该查询；如果密钥可以访问多个账户，也可以用它固定一个账户。

配置 MCP 客户端

Claude Code / Claude Desktop（~/.claude.json 或 claude_desktop_config.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 作为命令运行。

可用工具

共 57 个工具，覆盖 CallRail REST API v3 约 95% 的功能：读取工具、写入工具、追踪器配置、代理机构数据汇总、账户管理、通知、集成发现、外呼、离线潜在客户回填、潜在客户及跨渠道时间线、SMS 对话潜在客户管理，以及服务端分析。

读取工具

工具	用途
list_accounts	列出可访问的 CallRail 账户。fields="numeric_id" 会添加 CallRail URL 中显示的编号
list_companies	列出账户下的公司（客户）。可选参数：status="active"、search、fields（例如 verified_caller_ids）和 page
list_trackers	列出跟踪电话号码及其来源映射。可选参数：status="active"、type、search 和 fields
get_tracker	获取单个跟踪器的完整详情
list_calls	分页获取通话列表。可按公司、日期范围、answer_status、direction、device、call_type、lead_status、tracker_id、tags 和自由文本 search 进行筛选，并可指定 sort/order 和 IANA time_zone
get_call	获取特定通话的完整详情
call_summary	获取指定时间范围内的汇总统计数据（总量、人工接听、语音留言、未接来电、按来源统计、时长）
list_form_submissions	获取 CallRail 表单追踪提交记录。可按 lead_status、tags 和 person_lead 筛选；可按 submitted_at 或 form_url 排序
list_text_messages	获取 SMS 对话
list_users	分页获取账户用户。可按 company_id 筛选，按姓名和邮箱进行 search，并按 email 或 created_at 排序
get_call_recording	获取录音 URL（如果已启用录音）。CallRail 说明该链接至少在 24 小时内有效；HIPAA 账户会获得约 24 小时后过期的临时 URL
get_call_transcript	通过字段选择获取转录文本，以及 conversational_transcript、call_summary、call_highlights、keywords_spotted、sentiment 和 speaker_percent（自 2026-05-21 起需使用 Premium Conversation Intelligence）
search_calls_by_number	在指定时间范围内按电话号码查找通话（先在服务端用 search 缩小范围，再进行精确匹配）
list_tags	列出账户中的标签，或筛选指定公司的标签。可按 status 和 tag_level 筛选

写入工具

工具	用途
update_call	更新备注、标签、垃圾通话标记、客户姓名和潜在客户状态
add_call_tags / remove_call_tags	添加或移除标签（保留现有标签）
update_form_submission	更新备注、标签（替换，或通过 append_tags=True 添加）、value（按 CallRail 说明以货币字符串形式发送）和潜在客户状态。表单提交记录没有垃圾通话标记
create_tag / update_tag / delete_tag	对公司级和账户级（tag_level="account"）标签执行完整的 CRUD 操作。update_tag 还可停用或重新启用标签

跟踪器配置

工具	用途
create_tracker	配置新的跟踪号码。需要 confirm_billing=True，以防意外配置。支持来源跟踪器，以及包含 4 到 50 个号码的会话（DNI）池。按来源类型校验专属字段（search 对应 search_engine 和 search_type，落地页类型对应 landing，web_referrer 对应 referrer），还支持 swap_targets 和 campaign_name
update_tracker	更新可变设置：名称、转接目标、提示语、问候语（文本或录音 URL）、录音标记、SMS、交换目标和活动名称。读取当前通话流程并将更改合并其中；若流程为高级（IVR）流程，则拒绝覆盖
delete_tracker	软删除跟踪器（释放电话号码并保留历史记录）

账户管理

工具	用途
get_company / create_company / update_company / delete_company	完整的公司（客户）增删改查。免费，因为 CallRail 按号码而非公司收费。采用软删除语义。功能开关通过文档中说明的 PUT 字段设置（在 create_company 之后也要立即设置，因为 POST 仅接受名称和时区）；lead_scoring_enabled 在 API 中为只读，已弃用且无实际作用的开关会被移除，并发出警告
get_user / create_user / update_user / delete_user	完整的用户增删改查。create_user 通过电子邮件发送邀请；角色包括：admin、manager、reporting。update_user 只能更改姓名和公司访问权限，因为 API 无法更改用户的角色或电子邮件
get_tag	单个标签详情
get_form_submission	单个表单提交详情
get_text_message	包含所有消息的单条 SMS 对话
create_form_submission	手动创建表单提交（补录到店、纸质表单或线下线索）。需要 form_url 和 form_data，通过 session_id 或引荐来源三元组进行归因；备注、标签、价值和线索状态会通过后续更新应用

通知和集成

工具	用途
list_notifications / create_notification / update_notification / delete_notification	完整的用户级提醒规则增删改查（哪些用户会收到关于哪些电话、短信或表单事件的提醒）
list_integrations(company_id) / get_integration	查找关联到公司的 GMB、Google Ads、Facebook、Slack 和 Webhook 集成。CallRail 将 Webhook 视为一种集成类型，因此也可通过此工具检查 Webhook

外呼

工具	用途
create_outbound_call	拨打外呼电话。CallRail 会先拨打 business_phone_number，然后接通 customer_phone_number，并显示 caller_id。需要设置 confirm_dialing=True 作为安全保护，因为这会拨打真实电话、消耗通话时长，并涉及法律影响。仅限美国和加拿大。可选的 agent_id 用于将通话分配给某个用户

线索和服务器端分析

工具	用途
list_leads / get_lead_timeline	CallRail 去重后的个人记录（可按 created_at、name 或 email 排序），以及每条线索的完整跨渠道历史记录（电话、表单、短信），包含首次和最后一次触点归因
list_sms_threads / get_sms_thread / update_sms_thread	SMS 线程线索管理：像处理电话线索一样，为短信线索添加标签、备注并判定资格。线程可按日期范围筛选，并可按号码、姓名或标签搜索
call_stats	通过 /calls/summary.json 在服务器端汇总通话数据。可在一次请求中按公司、company_id、来源、关键词、营销活动、引荐来源、落地页或最后请求的页面分组，无需对每条通话进行分页。支持与 list_calls 相同的服务器端筛选条件（answer_status、direction、device、lead_status、first_time_callers、时长范围、tags、tracker_ids、search、time_zone）
call_timeseries	通话量趋势线。支持 interval（小时、日、周、月、年）、与 call_stats 相同的筛选条件，并会在发送请求前检查 CallRail 的 200 个数据点限制
form_stats	在服务器端汇总表单提交数。支持 group_by（来源、关键词、营销活动、引荐来源、落地页、表单名称、公司）、fields（total_forms、first_forms、leads）、lead_status 和 tags
get_call_page_views	查看访客在通话前浏览过的页面。与 call_eligibility_check 搭配使用以调试转化问题

代理机构汇总

工具	用途
usage_summary	按公司拆分本周期的成本归因：使用分钟数、启用的号码数、预估成本占比，并按成本驱动因素从高到低排序。回答“哪个客户正在消耗我的 CallRail 预算”
call_eligibility_check	审核指定通话是否符合 Google Ads 转化条件。检查是否存在 gclid、是否接听、通话时长是否达到 Google 的门槛（默认 60s），以及来源
compare_periods	将当前 N 天窗口与前一个窗口进行比较。按公司列出分钟数和通话数的变化，并指出变化最大的公司
bulk_update_calls	对符合筛选条件的所有通话应用一项更新（标签、备注、潜在客户状态、垃圾电话）。默认 dry_run=True，最多处理 500 通电话
spam_detector	通过启发式方式标记可能的垃圾电话（通话时长短、未接听、重复来电模式）。可选的 auto_tag=True 会添加 auto_detected_spam 标签。刻意不会设置 spam=True，因为这会导致默认 GET 请求隐藏该通电话

所有工具都可以选择性地接受 account_id；若省略，则会自动解析并缓存进程中第一个可访问的账户。设置 CALLRAIL_ACCOUNT_ID 可固定账户并跳过查询。大多数工具都接受 company_id，用于筛选单个客户。

关于通话筛选的说明

CallRail 的 GET /calls.json 接受 answer_status（answered、missed、voicemail），但没有 answered 或 source 参数。此服务的早期版本会转发这两个参数，而 CallRail 会静默忽略它们，因此结果看起来经过了筛选，实际上却没有。此问题已在 v1.2.0 中修复：

• answer_status 是有文档说明的筛选条件，会在服务端应用。
• answered 仍作为已弃用的别名保留，并会转换为 answer_status。
• source 在客户端应用，响应中会包含一个 source_filter 块，明确说明实际匹配的内容。若要按来源细分，请优先使用 call_stats(group_by="source")。

CallRail 还有两点让我吃过苦头：

• 在 CallRail 看来，语音留言也算已接听，因为是其系统接听了电话。从 v1.3.0 起，call_summary、spam_detector、call_eligibility_check 和 bulk_update_calls 只有在有人接听时才会将通话视为已接听（answered 且不是 voicemail），并单独报告语音留言。answer_status=missed 包含语音留言。
• 不指定日期窗口时，CallRail 会使用 recent 范围，即包括今天在内的前 7 天，而不是所有时间。支持时间窗口的工具接受 IANA time_zone，确保日期边界与客户的报告时区一致；usage_summary / compare_periods 会自动传递账户的时区。通信记录会保留 25 个月，因此若窗口范围超出该期限，工具会报错并要求缩小范围。

全程都会严格验证：电话号码格式、区号（^\d{3}$）、会话池大小（CallRail 的 4 到 50 范围）、名称、耳语提示和问候语长度上限，以及包含 12 个值的来源类型枚举。

丰富的字段选择

CallRail API 返回精简的默认载荷。可通过 fields 参数，为 list_calls、get_call 或 list_form_submissions 请求更多字段：

fields=company_name,source_name,keywords,landing_page_url,device_type,first_call,value,tags,note,gclid,fbclid,utm_source,utm_medium,utm_campaign,utm_content,utm_term,referrer_domain

也可以按名称请求会话智能和归因字段：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 官方 MCP 服务的对比

CallRail 提供官方托管 MCP 服务（文档见 apidocs.callrail.com），使用 OAuth 2.0，约有 30 个工具，服务 URL 由你的 CallRail 客户团队提供。如果你需要完全托管的远程服务，这是一个不错的选择。

我开发这个项目，是为了满足另一种需求：

	callrail-mcp（本项目）	CallRail 官方 MCP
安装	pip install callrail-mcp，两分钟即可运行	由你的 CallRail 客户团队提供 URL
托管方式	本地 stdio，因此 API 密钥不会离开你的设备	托管式远程服务（OAuth）
工具	57 个	约 30 个
代理机构工具	usage_summary 成本归属、compare_periods、spam_detector、bulk_update_calls、call_eligibility_check	未提供
安全防护	confirm_billing、confirm_dialing、默认启用 dry_run、严格的输入验证	未说明
源码	MIT 许可、开源、可审计	闭源

两者都使用相同的底层 REST API v3。如果你在一家代理机构管理多个客户账户，并需要成本归属和批量工作流，那么这个项目正是我为自己开发的。

社区还提供了一个 TypeScript 服务：npm 上的 @kanopi/callrail-mcp（34 个工具、stdio、API 密钥身份验证）。而我在这个项目中加入了代理机构工具、安全防护，以及根据 CallRail 文档和实时响应核验过的请求契约（参见 CHANGELOG 中的 1.3.0 条目）。

范围之外（有意未实现）

根据设计，以下 CallRail 功能不在此 MCP 服务中。如果你的账户支持这些功能，欢迎提交 PR；也可以提出 issue，我会优先处理。

受 CallRail 账户权限限制（返回 403）

这些端点确实存在，但需要升级账户或获得权限，而我的标准 CallRail 账户不具备这些条件。我在 2026-10-05 对它们进行了实时重新测试：

• 发送 SMS/MMS（POST /text-messages.json）需要 A2P/TCR SMS 注册。CallRail 会强制要求在外发短信中使用符合 TCPA 规范的关键词（STOP、CANCEL、UNSUBSCRIBE）。CallRail 于 2026-05-05 添加了 MMS 支持。
• 创建、更新和删除 Webhook 集成（POST /integrations.json，其中 type=Webhook）需要 Integration-Admin 权限。
• 外呼主叫号码（/caller_ids.json CRUD）有 CallRail 文档说明，但标准账户会返回 403。
• 消息流（/message-flows.json CRUD，SMS 自动回复流）有文档说明，但会返回 403。
• 集成筛选器（/integration_triggers.json CRUD）有文档说明，但会返回 403。
• 如果账户中没有任何公司启用表单跟踪，表单提交端点会返回 403。 这是账户状态而非权限问题：只需在一家公司启用表单跟踪，端点就会开放。工具会在错误信息中说明这一点。

CallRail REST API 未提供

这些功能没有对应的 API，只能通过 CallRail 网页界面管理：

• 号码：账户级别的号码所有权、移植和转移。
• 通话流程：IVR 构建器和通话路由树配置。
• 自定义字段 CRUD：自定义数据列可作为通话和表单响应的一部分读取，但不提供架构管理端点。
• 请勿来电名单：DNC 号码管理。

已可用但尚未发布

这些功能在标准账户中可读取，但目前我认为价值较低：summary_emails CRUD、companies/bulk_update.json（仅用于捕获外部表单），以及 form_submissions/ignored_fields.json。

示例

> List companies under our CallRail account.

(calls list_companies, returns clients with IDs and primary numbers)

> Pull today's calls for company COM019ab..., include source and keyword.

(calls list_calls with company_id, days=1, fields="source,keywords,landing_page_url")

> Why is my CallRail bill $174 this month? Break it down by client.

(calls usage_summary, returns per-company cost share sorted by biggest user)

> Why didn't this call show up as a conversion in Google Ads? CAL019dbf79...

(calls call_eligibility_check, returns gclid, duration, and answered checks
 plus a targeted reason such as "duration 58s under Google Ads minimum (60s)")

> Show me everything this lead has done with us.

(calls list_leads then get_lead_timeline, returns calls, forms, and texts in one timeline)

> Provision a new Google-Ads-call-extension tracker for Alan Construction in 412.

(calls create_tracker, refuses unless you also pass confirm_billing=True
 since it incurs a monthly charge)

直接使用 Python

CallRailClient 也可以作为库使用：

from callrail_mcp.client import CallRailClient

cr = CallRailClient()  # picks up 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"))

paginate() 可接受可选的 stats 字典，其中会报告 pages_fetched、items_yielded、total_records 和 truncated，让你可以判断结果是被截断的还是完整的。

直接运行服务

用于调试或验证密钥是否有效：

python -m callrail_mcp

该服务通过 MCP stdio 通信。它会等待 stdin 中的 JSON-RPC 消息。按 Ctrl-C 退出。

无需运行 MCP 循环即可对 API 密钥进行冒烟测试：

python -c "from callrail_mcp.client import CallRailClient; c=CallRailClient(); print(c.get('a.json'))"

速率限制

CallRail 文档说明的默认限制为：常规 API 请求每小时 1,000 次、每天 10,000 次；短信发送（每小时 150 次、每天 1,000 次）和外呼（每小时 100 次、每天 2,000 次）则有单独的限额。客户端会根据 Retry-After 标头重试 429 响应，并且仅对幂等方法（GET、PUT、DELETE、HEAD、OPTIONS）的 5xx 响应采用指数退避重试。5xx 响应时绝不重试 POST，因此即使响应丢失，也不会创建重复的追踪器。对于大量分页请求，建议使用内置的 paginate() 助手。

开发

git clone https://github.com/pghdma/callrail-mcp
cd callrail-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

请参阅 DEVELOPMENT.md，了解发布流程、值得注意的 API 特性以及此代码库遵循的约定。

贡献

欢迎贡献。请参阅 CONTRIBUTING.md，了解开发环境设置、测试约定和发布流程。请通过 GitHub Issues 提交问题，并遵守行为准则。

安全

如果发现安全漏洞，请按照 SECURITY.md 中的说明私下报告，而不要公开提交问题。

作者

Steve Japalucci，Pittsburgh Digital Marketing Agency 的创始人。我每天都会在自己的客户账户中使用此项目，因此问题能很快被发现并修复。请通过 [email protected] 联系我。

许可证

MIT。请参阅 LICENSE。版权所有 (c) 2026 Steve Japalucci / Pittsburgh Digital Marketing Agency。

免责声明

本项目是一个独立的开源集成项目，与 CallRail 无关联、未经其认可，也未获得其官方支持。“CallRail”是 CallRail, Inc. 的商标。所有产品名称、徽标和品牌均为各自所有者的财产。