callrail-mcp

<!-- mcp-name: io.github.pghdma/callrail-mcp -->

# callrail-mcp

[![PyPI version](https://img.shields.io/pypi/v/callrail-mcp.svg)](https://pypi.org/project/callrail-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/callrail-mcp.svg)](https://pypi.org/project/callrail-mcp/)
[![CI](https://github.com/pghdma/callrail-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pghdma/callrail-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/callrail-mcp)

A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the [CallRail REST API v3](https://apidocs.callrail.com/) to any MCP-compatible client (Claude Code, Claude Desktop, Cursor, and others).

Created by **[Steve Japalucci](https://github.com/pghdma)**, founder of [Pittsburgh Digital Marketing Agency (PGHDMA)](https://pghdma.com).

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

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

# Or with pip
pip install callrail-mcp
```

To install from source (latest unreleased):

```bash
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)

```bash
export CALLRAIL_API_KEY="your_key_here"
```

### Option 2: key file

```bash
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`)

```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

| Tool | Purpose |
|---|---|
| `list_accounts` | List accessible CallRail accounts |
| `list_companies` | List companies (clients) under an account. Optional `status="active"` filter and `page` |
| `list_trackers` | List tracking phone numbers and their source mapping. Optional `status="active"` filter |
| `get_tracker` | Full detail for one tracker |
| `list_calls` | Paginated call list. Filter by company, date, and `answer_status` |
| `get_call` | Full detail for a specific call |
| `call_summary` | Aggregate stats (total, answered, by source, duration) for a window |
| `list_form_submissions` | CallRail Form Tracking submissions |
| `list_text_messages` | SMS conversations |
| `list_users` | Account users |
| `get_call_recording` | Recording URL (if recording enabled) |
| `get_call_transcript` | Conversation Intelligence transcript (requires Premium CI since 2026-05-21) |
| `search_calls_by_number` | Find calls by phone number across a window |
| `list_tags` | List tags in an account or filtered to one company |

### Write tools

| Tool | Purpose |
|---|---|
| `update_call` | Update note, tags, spam flag, customer name, lead status |
| `add_call_tags` / `remove_call_tags` | Additive and subtractive tag changes (preserves existing) |
| `update_form_submission` | Same field surface as `update_call`, plus `value` (numeric, supported on form submissions but not on calls, where CallRail returns 500) |
| `create_tag` / `update_tag` / `delete_tag` | Full CRUD on the per-company tag taxonomy |

### Tracker provisioning

| Tool | Purpose |
|---|---|
| `create_tracker` | Provision a new tracking number. **Requires `confirm_billing=True`** as a safety guard against accidental provisioning. Supports source trackers and session (DNI) pools of 4 to 50 numbers |
| `update_tracker` | Update mutable settings: name, destination, whisper, greeting, SMS |
| `delete_tracker` | Soft-delete a tracker (releases the phone number, preserves history) |

### Account management

| Tool | Purpose |
|---|---|
| `get_company` / `create_company` / `update_company` / `delete_company` | Full company (client) CRUD. Free, since CallRail bills per number rather than per company. Soft-delete semantics |
| `get_user` / `create_user` / `update_user` / `delete_user` | Full user CRUD. `create_user` invites by email; roles: admin, manager, reporting |
| `get_tag` | Single tag detail |
| `get_form_submission` | Single form-submission detail |
| `get_text_message` | Single SMS conversation with all messages |
| `create_form_submission` | Manually create a form submission (backfill walk-in, paper-form, or offline leads) |

### Notifications and integrations

| Tool | Purpose |
|---|---|
| `list_notifications` / `create_notification` / `update_notification` / `delete_notification` | Full per-user alert-rule CRUD (who gets pinged on which call, text, or form event) |
| `list_integrations(company_id)` / `get_integration` | Discover GMB, Google Ads, Facebook, Slack, and Webhook integrations attached to a company. CallRail models webhooks as an integration type, so this is also how you inspect webhooks |

### Outbound calling

| Tool | Purpose |
|---|---|
| `create_outbound_call` | Place an outbound call. CallRail dials `business_phone_number` first, then bridges to `customer_phone_number`, showing `caller_id`. **Requires `confirm_dialing=True`** as a safety guard, since it dials real phones, costs minutes, and carries legal implications. US and Canada only |

### Leads and server-side analytics

| Tool | Purpose |
|---|---|
| `list_leads` / `get_lead_timeline` | CallRail's deduplicated person records, plus full cross-channel history (calls, forms, texts) per lead with first and last touch attribution |
| `list_sms_threads` / `get_sms_thread` / `update_sms_thread` | SMS-thread lead management: tag, note, and qualify texting leads the way you would calls |
| `call_stats` | Server-side call aggregation via `/calls/summary.json`. Group by company, company_id, source, keywords, campaign, referrer, landing_page, or last_requested_page in one request instead of paginating every call |
| `call_timeseries` | Call-volume trend line. Supports `interval` (hour, day, week, month, year) and guards CallRail's 200-data-point limit before sending |
| `form_stats` | Server-side form-submission totals |
| `get_call_page_views` | The visitor's page-view journey behind a call. Pairs with `call_eligibility_check` for conversion debugging |

### Agency aggregation

| Tool | Purpose |
|---|---|
| `usage_summary` | Per-company cost-attribution breakdown for the cycle: minutes used, active numbers, estimated cost share, sorted by biggest cost driver. Answers "which client is burning my CallRail budget" |
| `call_eligibility_check` | Audit whether a specific call qualifies as a Google Ads conversion. Checks `gclid` presence, answered status, duration against Google's threshold (default 60s), and source |
| `compare_periods` | Compare the current N-day window against the previous one. Per-company minute and call deltas plus biggest mover |
| `bulk_update_calls` | Apply one update (tag, note, lead_status, spam) to every call matching a filter. `dry_run=True` by default and capped at 500 calls |
| `spam_detector` | Heuristically flag likely-spam calls (short duration, unanswered, repeat-caller patterns). Optional `auto_tag=True` adds an `auto_detected_spam` tag. Deliberately does not set `spam=True`, which would hide the call from default GETs |

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:

- `answer_status` is the documented filter and is applied server-side.
- `answered` remains as a depre