callrail-mcp

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

Created by Steve Japalucci, founder of Pittsburgh Digital Marketing Agency (PGHDMA).

Works with both major versions of the MCP Python SDK (1.x and 2.x).

What you can ask your assistant 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 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

• "Why is my CallRail bill $174? Break it down by client"
• "Which client is the biggest minute user this cycle?"

Conversion debugging

• "Why didn't this call convert in Google Ads? CAL019..."
• "Is this 58-second call eligible to count as a Google Ads conversion?"

Lead management

• "Show me everything this person has ever done: calls, forms, texts"
• "Tag this SMS thread as a qualified lead and add a note"

Tag and 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 about $3/mo)

Installation

# Recommended: pipx for an 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 and 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

57 tools total, covering roughly 95% of CallRail's REST API v3 surface: read tools, write tools, tracker provisioning, agency aggregation, account management, notifications, integrations discovery, outbound calls, offline-lead backfill, leads and cross-channel timelines, SMS-thread lead management, and server-side analytics.

Read tools

Write tools

Tracker provisioning

Account management

Notifications and integrations

Outbound calling

Leads and server-side analytics

Agency aggregation

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.

A note on filtering calls

CallRail's GET /calls.json accepts answer_status (answered, missed, voicemail) but has no answered or source parameter. Earlier versions of this server forwarded both and CallRail silently ignored them, so results looked filtered but were not. Since v1.2.0: