callrail-mcp

A Model Context Protocol server that exposes the CallRail REST API v3 to any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.).

Created by Steve Japalucci — Founder of Pittsburgh Digital Marketing Agency (PGHDMA).

What you can ask Claude to do

Once installed, any MCP-aware assistant can answer things like:

Reporting

• "Pull last week's calls for Alan Construction, grouped by source"

• "Show me every missed call from Google Ads this month"

• "Find any calls from 412-555-1234 across all clients in the last 90 days"

• "Get the transcript for call CAL019abc..."

Agency cost attribution (new in v0.4)

• "Why is my CallRail bill $174? Break it down by client"

• "Which client is the biggest minute user this cycle?"

Conversion debugging (new in v0.4)

• "Why didn't this call convert in Google Ads? CAL019..."

• "Is this 58-second call eligible to count as a Google Ads conversion?"

Tag + tracker management

• "Tag this call as 'lead' and add a note"

• "Provision a new Google Ads call-extension tracker for Renaissance in area code 412" (requires confirm_billing=True — costs ~$3/mo)

Related MCP server: GA4 MCP Server

Installation

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

# Or with pip
pip install callrail-mcp

To install from source (latest unreleased):

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

Auth

Get an API key at Settings → API Keys in your CallRail account. You need Account Admin permission to create one.

Provide it one of two ways:

Option 1: environment variable (recommended for most setups)

export CALLRAIL_API_KEY="your_key_here"

Option 2: key file

mkdir -p ~/.config/callrail
echo "your_key_here" > ~/.config/callrail/api-key.txt
chmod 600 ~/.config/callrail/api-key.txt

Or override with CALLRAIL_API_KEY_FILE=/path/to/key.txt.

Configure your MCP client

Claude Code / Claude Desktop (~/.claude.json or claude_desktop_config.json)

{
  "mcpServers": {
    "callrail": {
      "command": "callrail-mcp",
      "env": {
        "CALLRAIL_API_KEY": "your_key_here"
      }
    }
  }
}

If you installed via pipx, callrail-mcp will be on your PATH automatically. Otherwise, point command at the full path to the executable.

Cursor / other clients

The server speaks standard MCP stdio. Any client that supports stdio MCP servers will work — just run callrail-mcp as the command.

Available tools

49 tools total — ~85% of CallRail's REST API v3 surface. Read tools, write tools, tracker provisioning, agency aggregation, account management (Companies/Users CRUD), notifications, integrations discovery, outbound calls, and offline-lead backfill via create_form_submission.

Read tools

Write tools (v0.2+)

Tracker provisioning (v0.3+)

Account management (v0.6+)

Notifications + Integrations (v0.7+)

Outbound calling (v0.7+)

Validation is strict: phone-number format, area code (^\d{3}$), pool_size ∈ [1, 50] (safety cap to prevent accidental 5-figure provisioning bills), name/whisper/greeting length caps, source-type enum (all, direct, offline, google_my_business, google_ad_extension, facebook_all, bing_all).

Agency aggregation (v0.4+)

All tools accept account_id optionally — if omitted, the first accessible account is auto-resolved. Most accept company_id to filter to a single client.

Out of scope (deliberately not implemented)

The following CallRail capabilities are NOT in this MCP, by design. PRs welcome if you have an account that supports them — or open an issue and we'll prioritize.

Blocked by CallRail account permissions (returns 403)

These endpoints exist but require account upgrades / additional permissions our standard CallRail account doesn't have. Verified live 2026-04-24:

• Send SMS (POST /text-messages.json) — needs A2P SMS registration / dedicated SMS API permission. CallRail enforces TCPA-compliance keywords (STOP / CANCEL / UNSUBSCRIBE) on outbound text messages.

• Webhook integration create / update / delete (POST /integrations.json with type=Webhook) — needs Integration-Admin permission. CallRail manages webhooks via the Integrations framework, not a standalone endpoint.

Not exposed by CallRail's REST API (UI-only on standard plans)

These have no API equivalent at all — managed exclusively via the CallRail web UI:

• Outbound Caller IDs — verification flow for outbound caller identification.

• Numbers — account-level number ownership, porting, transfers.

• Call Flows — IVR builder / call routing tree configuration.

• Custom Fields CRUD — custom data columns are readable as part of call/form responses but the schema management endpoint isn't exposed.

• Do Not Call list — DNC number management.

Will work on if/when

Either CallRail upgrades the API or the user upgrades their account permissions, the above can be added without breaking changes — we'd just expose them as new MCP tools.

Rich field selection

The CallRail API returns a lean default payload. Ask for more fields on list_calls / get_call / list_form_submissions via the fields parameter:

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

See the CallRail API docs for the full field catalog per resource.

Examples

Claude Code

> List companies under our CallRail account.

(Claude calls list_companies → returns clients with IDs and primary numbers)

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

(Claude 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.

(Claude 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...

(Claude calls call_eligibility_check → returns gclid/duration/answered checks
 + targeted reason like "duration 58s under Google Ads minimum (60s)")

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

(Claude calls create_tracker — refuses unless you also pass confirm_billing=True
 since it incurs a ~$3/mo charge)

Direct Python usage

The CallRailClient is also usable as a library:

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"))

Running the server directly

For debugging or to verify your key works:

python -m callrail_mcp

The server speaks MCP stdio. It will wait for JSON-RPC messages on stdin. Ctrl-C to exit.

To smoke-test the API key without running the MCP loop:

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

Rate limits

CallRail allows 60 requests/minute per API key. The client retries 429 responses using the Retry-After header, and 5xx responses with exponential backoff (max 3 retries by default). For heavy pagination, prefer the built-in paginate() helper which uses per_page=100 by default.

Development

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

Contributions welcome — see CONTRIBUTING.md for dev setup, test conventions, and release flow. Please file issues via GitHub Issues and follow the Code of Conduct.

Security

If you discover a security vulnerability, please report it privately per SECURITY.md instead of opening a public issue.

Author

Steve Japalucci — Founder of Pittsburgh Digital Marketing Agency. Reach out at s@pghdma.com.

License

MIT — see LICENSE. Copyright © 2026 Steve Japalucci / Pittsburgh Digital Marketing Agency.

Disclaimer

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. All product names, logos, and brands are property of their respective owners.