callrail-mcp is a Model Context Protocol (MCP) server for the CallRail REST API v3. Once you configure it in Claude Code, Claude Desktop, Cursor, or another MCP client, you can ask questions related to call tracking in natural language. The project is compatible with both major versions of the MCP Python SDK, 1.x and 2.x.
Primary uses This project is aimed at call tracking, lead management, conversion debugging, and agency cost attribution. Common example questions include: pulling a given customer's calls from last week grouped by source, viewing all missed calls this month, finding calls for a given number across all customers over the last 90 days, getting the call recording for a given call; breaking down CallRail billing by customer, finding the customer with the highest minute usage this cycle; checking why a given call did not convert in Google Ads, determining whether a 58-second call meets the conditions for a Google Ads conversion; viewing all of a person's calls, forms, and text messages, tagging a text message lead and adding a note; and tagging a call, provisioning a new Google Ads call extension tracker in a specified area code (requires confirm_billing=True, about $3 per month).
Main capabilities There are 57 tools in total, covering about 95% of the CallRail REST API v3 endpoints, including: read tools, write tools, tracker provisioning, agency aggregation, account management, notifications, integration discovery, outbound calls, offline lead backfill, lead and cross-channel timelines, text message lead management, and server-side analytics. All tools can optionally take account_id; if omitted, the first accessible account is automatically resolved and cached in the current process. You can skip the lookup or pin an account by setting CALLRAIL_ACCOUNT_ID. Most tools accept company_id to filter a single customer.
For filtering calls, CallRail's GET /calls.json supports answer_status (answered, missed, voicemail), but there is no answered or source parameter. Since v1.2.0, this server treats answer_status as a server-side filter, converts answered as a deprecated alias to answer_status, and applies source on the client side and inthe response returns source_filter to explain what was matched; for source breakdowns, it is recommended to use call_stats(group_by="source"). In addition, CallRail counts voicemail as answered; since v1.3.0, call_summary, spam_detector, call_eligibility_check, and bulk_update_calls consider a call answered only when a human answers (answered and not voicemail), and report voicemail separately; answer_status=missed includes voicemail. When there is no date window, CallRail returns the most recent range by default (the previous 7 days including today) rather than all time. Tools with windows support IANA time zones, and usage_summary / compare_periods automatically forward the account time zone. Communication records are retained for 25 months, and windows outside that range return an error requiring you to narrow the range.
Validation is strict, covering phone number format, area code (^\d{3}$), session pool size (CallRail's 4 to 50 range), name, whisper, and greeting length limits, as well as the 12-value source type enum.
Field selection The CallRail API returns a reduced set of fields by default. You can request more fields on list_calls, get_call, or list_form_submissions via the fields parameter, and it also supports retrieving conversation intelligence and attribution fields by name, such as lead_status, sentiment, call_summary, call_highlights, keywords_spotted, transcription, conversational_transcript, speaker_percent, milestones, timeline_url, msclkid, prior_calls, total_calls, person_id, etc. For the complete field catalog, see the CallRail API documentation.
Tool annotations Each tool declares MCP tool annotations: 33 read tools have readOnlyHint, deletes and bulk writes have destructiveHint, updates have idempotentHint, create_outbound_call has openWorldHint due to reaching the telephone network. Clients that support annotations can automatically approve reads and ask before writes.
How to use Install from source (latest unreleased version): You can get an API key in your CallRail account under Settings > API Keys; Account Admin permission is required to create one. There are two ways to provide the key: an environment variable (recommended in most scenarios) or a key file; you can also override with CALLRAIL_API_KEY_FILE=/path/to/key.txt. Optional fixed account: each tool resolves the account id once per process via GET /a.json and caches it; setting CALLRAIL_ACCOUNT_ID skips the lookup, or pins one account when the key can access multiple accounts.
Configure the MCP client: In Claude Code / Claude Desktop (~/.claude.json or claude_desktop_config.json), if installed via pipx then callrail-mcp is automatically in PATH; otherwise point command to the full path of the executable. Cursor and other clients: the server uses standard MCP stdio, and any client that supports stdio MCP servers can run callrail-mcp as a command.
Running the server directly can be used for debugging or verifying the key: the server waits for JSON-RPC messages on stdin; press Ctrl-C to exit. You can also smoke-test the API key without running the MCP loop.
Using as a Python library CallRailClient can also be used as a library. paginate() accepts an optional stats dictionary, reporting pages_fetched, items_yielded, total_records, and truncated, making it easy to distinguish truncated results from complete results.
Comparison with the official MCP server CallRail officially provides a hosted MCP server (documentation at apidocs.callrail.com), using OAuth 2.0, with about 30 tools; the server URL is provided by the CallRail account team, suitable for a fully managed remote server. This project uses the same underlyingREST API v3 as the official server, but focuses on agency tooling, safety guardrails, and request contracts checked against CallRail documentation and actual responses. There is also a community TypeScript server @kanopi/callrail-mcp (npm, 34 tools, stdio, API key authentication).
Intentionally unimplemented scope The following capabilities are not in this MCP by design. Limited by CallRail account permissions (returns 403): sending SMS/MMS (POST /text-messages.json) requires A2P/TCR SMS registration; CallRail enforces TCPA compliance keywords (STOP, CANCEL, UNSUBSCRIBE) for outbound SMS; MMS support was added by CallRail on 2026-05-05; Webhook integration create, update, delete (POST /integrations.json with type=Webhook) requires Integration-Admin permission; outbound caller ID (/caller_ids.json CRUD) is documented but returns 403 for standard accounts; message flows (/message-flows.json CRUD, SMS auto-reply flows) are documented but return 403; integration triggers (/integration_triggers.json CRUD) are documented but return 403. The form submissions endpoint returns 403 when no company under an account has Form Tracking enabled; this is an account state rather than a permission issue, and the endpoint becomes available after Form Tracking is enabled; the tool will explain this in the error.
Capabilities not exposed by the CallRail REST API (managed only through the Web UI): numbers (account-level number ownership, number porting and transfer), call flows (IVR builder and call routing tree configuration), custom fields CRUD (custom data columns can be read as part of call and form responses, but schema management endpoints are not exposed), Do Not Call list (DNC number management).
Readable but not yet released features: readable by standard accounts but considered low value, including summary_emails CRUD, companies/bulk_update.json (external form capture only), and form_submissions/ignored_fields.json.
Limits and Quotas CallRail documentation defaults to a general limit of 1,000 API requests per hour and 10,000 per day; SMS sending has a separate budget of 150 per hour and 1,000 per day; outbound calls are 100 per hour and 2,000 per day. The client retries 429 responses using the Retry-After header, and for 5xx responses uses exponential backoff retries only for idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS). POST is never retried on 5xx, so a lost response will not create a duplicate tracker. For heavy pagination, using the built-in paginate() helper is recommended.
Other Information The project uses the MIT License, Copyright (c) 2026 Steve Japalucci / Pittsburgh Digital Marketing Agency. This project is an independent open-source integration and is not affiliated with, endorsed by, or officially supported by CallRail. "CallRail" is a trademark of CallRail, Inc. For the development process, API quirks, and codebase conventions, see DEVELOPMENT.md; for contribution guidelines, see CONTRIBUTING.md; security issues are reported privately according to SECURITY.md.
