Skip to main content
Glama
CallRail MCP

CallRail MCP

by pghdma

callrail-mcp

PyPI version Python versions CI License: MIT MCP Available on CodeGuilds

A Model Context Protocol server for the CallRail REST API v3. Point Claude Code, Claude Desktop, Cursor, or any other MCP client at it and ask about your call tracking in plain English.

I'm Steve Japalucci. I run Pittsburgh Digital Marketing Agency (PGHDMA), and I built this for my own client work. CallRail bills per tracking number and per minute across every client I manage, and I was tired of clicking through its reports to answer questions like "which client is burning my minutes this month". Now I ask Claude.

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

What I use it for

These are the kinds of questions I ask it every week:

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)

Related MCP server: Kommo CRM MCP Server

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:

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.

Optional: pin the account

Every tool resolves the account id with one GET /a.json per process and caches it. Set CALLRAIL_ACCOUNT_ID to skip that lookup, or to pin one account when the key can see several.

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

Tool

Purpose

list_accounts

List accessible CallRail accounts. fields="numeric_id" adds the number shown in CallRail URLs

list_companies

List companies (clients) under an account. Optional status="active", search, fields (for example verified_caller_ids) and page

list_trackers

List tracking phone numbers and their source mapping. Optional status="active", type, search and fields

get_tracker

Full detail for one tracker

list_calls

Paginated call list. Filter by company, date window, answer_status, direction, device, call_type, lead_status, tracker_id, tags and free-text search, with sort/order and an IANA time_zone

get_call

Full detail for a specific call

call_summary

Aggregate stats (total, answered by a person, voicemail, missed, by disposition, by source, duration) for a window

list_form_submissions

CallRail Form Tracking submissions. Filter by lead_status, tags and person_lead; sort by submitted_at or form_url

list_text_messages

SMS conversations

list_users

Account users, paginated. Filter by company_id, search names and emails, sort by email or created_at

get_call_recording

Recording URL (if recording enabled). CallRail documents the link as good for at least 24 hours; HIPAA accounts get a temporary URL that expires in about 24 hours

get_call_transcript

Transcript plus conversational_transcript, call_summary, call_highlights, keywords_spotted, sentiment and speaker_percent via field selection (Premium Conversation Intelligence required since 2026-05-21)

search_calls_by_number

Find calls by phone number across a window (narrowed server-side with search, then matched exactly)

list_tags

List tags in an account or filtered to one company. Filter by status and tag_level

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

Note, tags (replace, or add with append_tags=True), value (sent as the currency string CallRail documents) and lead status. Form submissions have no spam flag

create_tag / update_tag / delete_tag

Full CRUD on company-level and account-level (tag_level="account") tags. update_tag can also disable or re-enable a tag

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. Source-specific fields are validated per type (search_engine and search_type for search, landing for the landing types, referrer for web_referrer), plus swap_targets and campaign_name

update_tracker

Update mutable settings: name, destination, whisper, greeting (text or recording URL), recording flag, SMS, swap targets, campaign name. Reads the current call flow and merges your change into it, and refuses to overwrite an advanced (IVR) flow

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. Feature toggles go through the documented PUT fields (also right after create_company, since POST accepts only name and time zone); lead_scoring_enabled is read-only in the API and the deprecated no-op toggles are dropped with a warning

get_user / create_user / update_user / delete_user

Full user CRUD. create_user invites by email; roles: admin, manager, reporting. update_user changes names and company access only, because the API cannot change a user's role or email

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). Requires form_url and form_data, attribution via session_id or the referrer trio; note, tags, value and lead status are applied with a follow-up update

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. Optional agent_id assigns the call to a user

Leads and server-side analytics

Tool

Purpose

list_leads / get_lead_timeline

CallRail's deduplicated person records (sortable by created_at, name or email), 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. Threads can be windowed by date and searched by number, name or tag

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. Takes the same server-side filters as list_calls (answer_status, direction, device, lead_status, first_time_callers, duration bounds, tags, tracker_ids, search, time_zone)

call_timeseries

Call-volume trend line. Supports interval (hour, day, week, month, year), the same filters as call_stats, and guards CallRail's 200-data-point limit before sending

form_stats

Server-side form-submission totals. group_by (source, keywords, campaign, referrer, landing_page, form_name, company), fields (total_forms, first_forms, leads), lead_status and tags

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 and cached for the process. Set CALLRAIL_ACCOUNT_ID to pin it and skip the lookup. Most tools 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. I fixed that in v1.2.0:

  • answer_status is the documented filter and is applied server-side.

  • answered remains as a deprecated alias that translates to answer_status.

  • source is applied client-side, and the response includes a source_filter block stating exactly what was matched. For source breakdowns, prefer call_stats(group_by="source").

Two more things CallRail does that bit me:

  • Voicemail counts as answered on CallRail's side, because its system picked up. Since v1.3.0 call_summary, spam_detector, call_eligibility_check and bulk_update_calls treat a call as answered only when a person answered (answered and not voicemail) and report voicemail separately. Since v1.3.2 they use CallRail's call_disposition field when it is present, which also separates abandoned and Voice Assist calls. answer_status=missed includes voicemail.

  • No date window means CallRail's recent range, the previous 7 days including today, not all time. Windowed tools accept an IANA time_zone so day boundaries match the client's reporting zone, and usage_summary / compare_periods forward the account's zone automatically. Communication Records are retained for 25 months, so a window reaching past that returns an error asking for a narrower range.

Validation is strict throughout: phone-number format, area code (^\d{3}$), session pool size (CallRail's 4 to 50 range), name, whisper, and greeting length caps, and a 12-value source-type enum.

Rich field selection

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

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

Conversation-intelligence and attribution fields are also available by name: call_disposition, lead_status, lead_score, sentiment, call_summary, call_highlights, keywords_spotted, transcription, conversational_transcript, speaker_percent, milestones, timeline_url, msclkid, prior_calls, total_calls, person_id. See the CallRail API docs for the full field catalog per resource.

Tool annotations

Every tool declares MCP tool annotations: readOnlyHint on the 33 read tools, destructiveHint on deletes and bulk writes, idempotentHint on updates, and openWorldHint on create_outbound_call because it reaches the phone network. Clients that honor annotations can auto-approve reads and ask before writes.

How this compares to CallRail's official MCP server

CallRail offers an official hosted MCP server (documented at apidocs.callrail.com) using OAuth 2.0, with roughly 30 tools and a server URL provided by your CallRail account team. It is a good option if you want a fully managed remote server.

I built this one for a different job:

callrail-mcp (this project)

Official CallRail MCP

Install

pip install callrail-mcp, running in two minutes

URL provisioned by your CallRail account team

Hosting

Local stdio, so your API key never leaves your machine

Hosted remote (OAuth)

Tools

57

~30

Agency tooling

usage_summary cost attribution, compare_periods, spam_detector, bulk_update_calls, call_eligibility_check

Not offered

Safety guards

confirm_billing, confirm_dialing, dry_run defaults, strict input validation

Not documented

Source

MIT, open, auditable

Closed

Both speak the same underlying REST API v3. If you run an agency across many client accounts and want cost attribution and bulk workflows, this is the one I built for myself.

A community TypeScript server also exists, @kanopi/callrail-mcp on npm (34 tools, stdio, API key auth). What I put into this one instead is the agency tooling, the safety guards, and request contracts checked against CallRail's documentation and live responses (see the 1.3.0 entry in the CHANGELOG).

Out of scope (deliberately not implemented)

The following CallRail capabilities are not in this MCP, by design. PRs are welcome if you have an account that supports them, or open an issue and I will prioritize.

Blocked by CallRail account permissions (returns 403)

These endpoints exist but need account upgrades or permissions that my standard CallRail account does not have. I re-probed them live on 2026-10-05:

  • Send SMS/MMS (POST /text-messages.json) needs A2P/TCR SMS registration. CallRail enforces TCPA-compliance keywords (STOP, CANCEL, UNSUBSCRIBE) on outbound text messages. MMS support was added by CallRail on 2026-05-05.

  • Webhook integration create, update, delete (POST /integrations.json with type=Webhook) needs Integration-Admin permission.

  • Outbound Caller IDs (/caller_ids.json CRUD) is documented by CallRail but returns 403 on a standard account.

  • Message Flows (/message-flows.json CRUD, SMS auto-reply flows) is documented but returns 403.

  • Integration Filters (/integration_triggers.json CRUD) is documented but returns 403.

  • Form submission endpoints return 403 when no company on the account has Form Tracking enabled. That is account state rather than a permission: enable Form Tracking on one company and the endpoints open up. The tools say so in the error.

Not exposed by CallRail's REST API

These have no API equivalent and are managed exclusively via the CallRail web UI:

  • Numbers: account-level number ownership, porting, and transfers.

  • Call Flows: the IVR builder and call routing tree configuration.

  • Custom Fields CRUD: custom data columns are readable as part of call and form responses, but the schema management endpoint is not exposed.

  • Do Not Call list: DNC number management.

Available but not yet shipped

Readable on a standard account, but I have judged them low value so far: summary_emails CRUD, companies/bulk_update.json (external form capture only), and form_submissions/ignored_fields.json.

Examples

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

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

paginate() accepts an optional stats dict that reports pages_fetched, items_yielded, total_records, and truncated, so you can tell a capped result from a complete one.

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. Press 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's documented default limits are 1,000 requests per hour and 10,000 per day for general API requests, with separate budgets for SMS sends (150 per hour, 1,000 per day) and outbound calls (100 per hour, 2,000 per day). The client retries 429 responses using the Retry-After header, and retries 5xx responses with exponential backoff for idempotent methods only (GET, PUT, DELETE, HEAD, OPTIONS). POST is never retried on 5xx, so a lost response cannot create duplicate trackers. For heavy pagination, prefer the built-in paginate() helper.

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

See DEVELOPMENT.md for release flow, API quirks worth knowing, and the conventions this codebase follows.

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. I use this on my own client accounts every day, so bugs get noticed and fixed fast. Reach out at s@pghdma.com.

License

MIT. See LICENSE. Copyright (c) 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.

Available Tools

57 tools
add_call_tagsA
Idempotent

Append tags to a call WITHOUT replacing existing ones.

Reads the call's current tags first, merges the new ones in, then PUTs the combined list. Use this when you want to add labels (e.g. 'lead', 'spam', 'follow-up') without losing prior tags. To fully replace tags, use update_call(tags=[...]) instead.

Auto-creates company-level tags for any name not already in the system (CallRail's default behavior). Empty/whitespace-only entries are silently filtered, so add_call_tags(['', 'lead']) won't 400 (only 'lead' is sent).

Args: call_id: 'CAL...' id. tags: Tag names to add. Strings only; non-strings are dropped with a warning. De-duplicated. Max 100 tags per request. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated call object (showing the merged tag list). Errors if no valid tags remain after cleaning.

Inputs: tags (required), call_id (required), account_id. Returns: result

bulk_update_callsA
Destructive

Apply the same update to every call matching a filter.

Useful for: "tag every Bing call this month as low-priority", "mark all <30s unanswered calls from this number as spam", "add a note to every call from a specific landing page". Replaces dozens of sequential update_call invocations with one tool call.

Safety: dry_run=True by default, so this tool returns a preview of which calls WOULD be updated without actually writing. Pass dry_run=False to commit. Hard cap of 500 calls per invocation to prevent runaway bulk operations.

Args: company_id, days: filter (same semantics as list_calls). At least one filter must be provided to avoid "update everything ever". answer_status: server-side filter. One of 'answered', 'missed', or 'voicemail'. 'missed' includes calls that reached voicemail. answered: DEPRECATED alias ('true' -> answered, 'false' -> missed). Before v1.2.0 this was forwarded as an answered query param that CallRail does not implement: the filter was silently dropped, so a commit run updated EVERY call in the window. source: applied CLIENT-SIDE (exact, case-insensitive match on each call's source field) because CallRail has no server-side source filter. Matching happens before the 500-cap is applied. set_tags_add: tag names to ADD to each matched call (preserves existing tags). Mutually compatible with other set_* fields. set_note: note text to set on each matched call (replaces existing). set_lead_status: e.g. 'good_lead', 'not_a_lead'. set_spam: True to mark spam. NOTE: CallRail does not support un-marking spam via the API, so set_spam=False is rejected. dry_run: If True (default), return preview only. False = commit. account_id: Auto-resolves if omitted.

Returns: - If dry_run: {"dry_run": true, "matched": N, "would_update_calls": [...], "set_fields": {...}} - Else: {"dry_run": false, "matched": N, "updated": M, "failed_count": K, "failures": [...]}

Performance note: when set_tags_add is used, the commit phase issues 1 extra GET per call to fetch fresh tags before merging (race protection against concurrent tag writes). For a max bulk of 500 calls, this is ~2× the latency vs other set_* fields. Other update fields (note, lead_status, spam) skip the extra GET.

Inputs: days, source, dry_run, answered, +7 more. Returns: result

call_eligibility_checkA
Read-onlyIdempotent

Audit whether a specific call is/was eligible to count as a Google Ads conversion. Useful for "where did my conversion go" debugging.

Checks:

  1. Did the call have a gclid? (Required for CallRail to upload to Google Ads as a UPLOAD_CLICKS Phone Call conversion.)

  2. Was the call answered? (Most integrations skip unanswered.)

  3. Did duration meet Google Ads' minimum? (Default 60s; configurable per conversion action in Google Ads UI.)

  4. Is the call from a Google source? Detection uses CallRail's internal source slug (e.g. google_paid, google_my_business)

    • presence of gclid, NOT the user-editable source_name display string (which can mislead, e.g. "Bing Ads (Google legacy import)" would substring-match as Google but is clearly Bing).

Args: call_id: 'CAL...' id. google_ads_min_duration_seconds: Threshold to check duration against. Defaults to 60 (Google's UI default). Override if you've lowered it on a specific conversion action. account_id: Auto-resolves if omitted.

Returns: Verdict + each criterion's pass/fail + suggested remediation when eligibility fails.

Inputs: call_id (required), account_id, google_ads_min_duration_seconds. Returns: result

call_statsA
Read-onlyIdempotent

Server-side call aggregation via CallRail's /calls/summary.json.

One request instead of paginating every call. Prefer this over call_summary (which fetches and counts calls client-side) when you only need grouped totals. call_summary remains useful for metrics this endpoint doesn't expose (first-time vs repeat split, per-source-name breakdown, exact duration sums).

Args: group_by: Dimension to group by. One of: 'source', 'keywords', 'campaign', 'referrer', 'landing_page', 'company'. days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. fields: Comma-separated metrics, e.g. 'total_calls,missed_calls,answered_calls,first_time_callers, average_duration,leads'. Default: total_calls only. account_id: Auto-resolves if omitted.

Returns: JSON string with start_date, end_date, time_zone, total_results and grouped_results[] ({key, }).

Server-side filters (documented, live-verified 2026-10-05): answer_status ('answered' | 'missed' | 'voicemail'; missed includes voicemail), direction, device, lead_status ('good_lead' | 'not_a_lead' | 'not_scored'), first_time_callers, min_duration / max_duration (seconds), tags (any of), tracker_ids, search (phone fragment, name, note, source) and time_zone (IANA; also sets "today" for days). fields is validated against VALID_CALL_STATS_FIELDS.

Inputs: days, tags, device, fields, +14 more. Returns: result

call_summaryA
Read-onlyIdempotent

Summarize calls over a date window.

Returns counts: total, answered/missed, first-time/repeat callers, total duration, and breakdowns by source and source_name. Useful for weekly/monthly rollups without pulling every call into context.

Counting rule: missed includes calls that reached voicemail, exactly as CallRail's own answer_status=missed filter and dashboard do, even though CallRail marks those calls answered=true. voicemail reports that subset separately. by_disposition breaks the window down by CallRail's call_disposition (answered, missed, abandoned, voicemail, voicemail_abandoned, voice_assist; outbound calls show as "outbound").

Note: requires days>=1 or an explicit start_date. Without a window this would paginate the entire account history (potentially 50+ pages of 250 calls each), which is rarely what callers want.

time_zone (IANA) aligns CallRail's day boundaries with the window and is used to compute "today" for days.

Inputs: days, end_date, time_zone, account_id, +2 more. Returns: result

call_timeseriesA
Read-onlyIdempotent

Call volume over time via CallRail's /calls/timeseries.json. One request for a trend line instead of client-side bucketing.

CallRail refuses any request whose result set would exceed 200 data points. With the default daily interval that caps the window at ~200 days; use interval='week' or 'month' for longer ranges. This tool checks the limit before sending so you get a clear message instead of a raw 400.

Args: days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. fields: Comma-separated metrics. Valid: total_calls, missed_calls, answered_calls, abandoned_calls, first_time_callers, average_duration, formatted_average_duration, leads. interval: Bucket size. One of 'hour', 'day', 'week', 'month', 'year'. Defaults to CallRail's own choice (daily) when omitted. account_id: Auto-resolves if omitted.

Returns: JSON string with total_results and data[], one entry per bucket ({key/date, }).

Server-side filters (documented, live-verified 2026-10-05): answer_status ('answered' | 'missed' | 'voicemail'; missed includes voicemail), direction, device, lead_status ('good_lead' | 'not_a_lead' | 'not_scored'), first_time_callers, min_duration / max_duration (seconds), tags (any of), tracker_ids, search (phone fragment, name, note, source) and time_zone (IANA; also sets "today" for days). fields is validated against VALID_CALL_STATS_FIELDS.

Inputs: days, tags, device, fields, +14 more. Returns: result

compare_periodsA
Read-onlyIdempotent

Compare current N-day window vs the previous N-day window.

Returns per-company minute / call deltas + agency-wide totals. Useful for "is Malick growing?", "did we lose Stewart traffic this month?", catching invoice surprises before they hit.

Args: days: Window length on each side (default 30 = roughly one cycle). Cap: 365 (don't ask for "5-year delta", likely a typo). account_id: Auto-resolves if omitted.

Returns: A breakdown showing current vs previous totals, % deltas, and per-company growth/shrink. Sorted by absolute minute change.

Implementation: pulls call data for both windows in one tool call. Tracker counts use current-snapshot for both periods (CallRail doesn't expose historical tracker counts); only minute deltas reflect actual period-over-period change.

Inputs: days, account_id. Returns: result

create_companyA

Create a new company (client) under the account.

Useful for new-client onboarding. CallRail bills per number, not per company: creating a company is free; provisioning trackers under it is what costs money (see create_tracker).

CallRail's POST /companies accepts only name and time_zone. Every feature toggle is a PUT field, so when any toggle is given this tool creates the company and then applies the toggles with a second call; the response carries settings_applied (or settings_not_applied plus api_warnings if that second call failed).

Args: name: Display name (e.g. "Smith & Co Roofing"). Required. time_zone: IANA TZ. Default 'America/New_York' (matches your existing companies). Common: 'America/Los_Angeles', 'America/Chicago', 'America/Denver'. callscore_enabled: CallRail CallScore AI scoring (paid feature). Pass None (default) to inherit the account default. lead_scoring_enabled: NOT settable via the API (read-only field); passing it returns an error. Toggle it in the CallRail UI. swap_exclude_jquery: Deprecated by CallRail, has no effect. Not sent; reported under api_warnings. callscribe_enabled: Conversation Intelligence transcripts (paid). None=inherit. keyword_spotting_enabled: Deprecated by CallRail, has no effect. Not sent; reported under api_warnings. form_capture: Enable CallRail Form Tracking (sent as the PUT field external_form_capture). None=inherit. account_id: Auto-resolves if omitted.

Note: Optional booleans default to None (inherit account-level defaults) rather than False. Sending False for a paid feature on an account that has it enabled would actively DISABLE it, almost never the caller's intent on a fresh-create.

Inputs: name (required), time_zone, account_id, form_capture, +5 more. Returns: result

create_form_submissionA

Manually create a form submission (e.g. backfill an offline lead).

Useful when you receive a lead through a non-CallRail-tracked channel (paper form, in-person, etc.) and want it visible in CallRail with proper attribution + lead-status workflow.

CallRail's POST /form_submissions accepts exactly: company_id, form_url, form_data, and EITHER session_id OR all three of referrer / referring_url / landing_page_url. It parses phone numbers out of form_data to find or create the person, so put the customer's phone, name and email inside form_data (there are no customer_* body fields).

Args: company_id: 'COM...' id. Required. form_url: URL of the page the form was submitted to. Required. form_data: Dict of form-field values, e.g. {"name": "Kevin", "email": "k@x.com", "phone": "412-555-1234"}. Required and non-empty. referrer / referring_url / landing_page_url: Attribution. All three are required unless session_id is given. Use the original web context if known, or "(direct)" / "https://offline" placeholders for in-person leads. session_id: 'SES...' id of an existing web session; replaces the three attribution fields. note, tags, value, lead_status: Lead-management fields. The POST endpoint does not accept them, so they are applied with a follow-up PUT; the response reports lead_fields_applied or lead_fields_not_applied (plus api_warnings). value is sent as a currency string ("12.50"); lead_status is 'good_lead' or 'not_a_lead'. account_id: Auto-resolves if omitted.

Inputs: form_url (required), form_data (required), company_id (required), note, +8 more. Returns: result

create_notificationA

Create a notification rule (who gets pinged on which event).

Args: alert_type: Which calls trigger the rule. One of 'all', 'first_call', 'missed_and_vm', 'vm_only'. Required when call_enabled is true; omit for SMS-only rules. user_id: 'USR...' id of the user being notified. If neither user_id nor email is given, CallRail assigns the rule to the user who owns the API key. company_id, tracker_id: Optional scope filters. send_email / send_desktop / send_push: Channel toggles. call_enabled / sms_enabled: Trigger toggles; set call_enabled for call alerts and sms_enabled for text alerts. email: Creates an email-only recipient instead of a user. CallRail requires a company_id or tracker_id with it and allows only send_email. agent_id: 'USR...' id of the agent whose calls trigger the rule. name: Accepted for backward compatibility and NOT sent: CallRail generates the name from the configuration. account_id: Auto-resolves if omitted.

Inputs: name, email, user_id, agent_id, +9 more. Returns: result

create_outbound_callA

Place an outbound call. THIS ACTUALLY DIALS REAL PHONES.

CallRail dials business_phone_number FIRST; once that leg is answered it dials customer_phone_number and bridges the two. Both legs cost minutes against your bundle. Misuse can constitute unlawful telemarketing, so verify consent.

US and Canadian numbers only (CallRail does not support outbound to the UK or Australia via this endpoint).

You must pass confirm_dialing=True to actually place the call.

Args: caller_id: The number shown to the recipient. Must be one of your CallRail tracking numbers or a verified Outbound Caller ID. E.164 format. business_phone_number: The FIRST leg CallRail dials (your agent's phone). E.164 format. customer_phone_number: The SECOND leg, bridged in once the business leg answers. E.164 format. confirm_dialing: REQUIRED. Set True to actually dial. Returns an error envelope if False (default). recording_enabled: Record this call. outbound_greeting_text: Text-to-speech greeting played to the customer. outbound_greeting_recording_url: Public URL of an audio greeting, used instead of outbound_greeting_text. agent_id: 'USR...' id of the user to assign to the call. account_id: Auto-resolves if omitted.

Returns: The call object CallRail creates (id, etc.).

NOTE (v1.2.0): earlier versions sent {"from", "to"}, which are not fields CallRail accepts, so every call failed. The parameter names above match the documented request body.

Inputs: caller_id (required), business_phone_number (required), customer_phone_number (required), agent_id, +5 more. Returns: result

create_tagA

Create a new tag, scoped to one company or to the whole account.

Args: name: Tag display name. company_id: 'COM...' id. Required for company-level tags (the default). Omit it when tag_level='account'. account_id: Auto-resolves if omitted. color: One of the 24 CallRail-supported colors (see VALID_TAG_COLORS): gray1-2, blue1-2, cyan1-2, purple1-2, pink1-4, red1-2, orange1-4, yellow1-2, green1-4. If omitted, CallRail defaults to 'gray1'. tag_level: 'company' (default) or 'account'. Account-level tags apply to every company and can only be created by administrators.

Inputs: name (required), color, tag_level, account_id, +1 more. Returns: result

create_trackerA

⚠️ Create a new tracking phone number (tracker). THIS COSTS MONEY.

CallRail charges per provisioned number. Typical pricing as of 2026:

  • Local numbers: ~$3/month each

  • Toll-free (8XX): ~$3-5/month each

  • Session pools: charged per number × pool_size (so pool_size=8 = 8x)

  • Plus per-minute usage (~$0.05/min on answered calls)

Most plans bundle 5-10 numbers; provisioning beyond your bundle adds overage charges. Some plans prorate partial-month usage, so creating and immediately deleting can still produce a small charge depending on your contract.

You must pass confirm_billing=True to actually create. This guards against accidental provisioning when an AI is exploring tools.

Args: name: Display name for the tracker (e.g. "Google Ads Call Extension"). company_id: 'COM...' id of the company this tracker belongs to. destination_number: Where calls forward to, e.g. "+14129548337". confirm_billing: REQUIRED. Set True to acknowledge the per-number cost. Returns an error envelope if False (default). type: 'source' (single number tied to one traffic source) or 'session' (DNI pool that swaps numbers per visitor). Default 'source'. source_type: For type='source', which traffic source. One of VALID_SOURCE_TYPES: 'all', 'landing_url', 'landing_params', 'offline', 'web_referrer', 'direct', 'search', 'google_ad_extension' (what Google Ads call extensions use), 'mobile_ad_extension', 'google_my_business', plus the production-observed 'facebook_all' and 'bing_all'. Ignored for type='session'. area_code: 3-digit area code to provision the local number from (e.g. '412'). Ignored if toll_free=True. toll_free: If True, provision an 8XX toll-free number instead. pool_size: For type='session' only. How many numbers in the DNI pool. CallRail requires 4-50; each pool number is billed separately, so this multiplies your monthly cost. whisper_message: Spoken to the agent answering the call so they know which marketing source it came from. recording_enabled: Record the call audio. Default True. greeting_text: Optional automated greeting text-to-speech. sms_enabled: Allow this number to receive/send SMS. Default True. search_engine / search_type: Required when source_type='search'. search_engine is 'google' | 'yahoo' | 'bing' | 'all'; search_type is 'paid' | 'organic' | 'all' (so Google Ads traffic is search_engine='google', search_type='paid'). landing: Required for source_type='landing_url' (a page, e.g. 'www.example.com/promo1') or 'landing_params' (a query string fragment, e.g. 'promo=1'). referrer: Required for source_type='web_referrer' (a referring site, e.g. 'facebook.com'). swap_targets: Phone numbers on the website that this tracker's number should replace (any formatting). Defaults to the destination number when omitted. campaign_name: Campaign label for reports. Source trackers only. account_id: Auto-resolves if omitted.

Returns the created tracker including its newly-provisioned tracking_numbers.

Inputs: name (required), company_id (required), destination_number (required), type, +16 more. Returns: result

create_userA

Invite a new user. CallRail emails them an account-creation link.

Args: email: Recipient email. CallRail sends an invite. first_name, last_name: Display name. role: Default 'reporting' (read-only). Documented values: 'admin', 'manager', 'reporting'. CallRail's docs also mention legacy "notification" users, so unknown values are passed through with a warning instead of rejected. company_ids: List of 'COM...' company IDs the user can access. REQUIRED by CallRail for manager and reporting roles (sent as the documented companies field). Admins see every company. account_id: Auto-resolves if omitted.

Note: This sends an invitation email. Don't run experimentally.

Inputs: email (required), last_name (required), first_name (required), role, +2 more. Returns: result

delete_companyA
DestructiveIdempotent

Soft-delete a company. Status flips to 'disabled', records retained.

Mirrors delete_tracker semantics: CallRail's DELETE on companies is a soft-delete. Use list_companies(status="active") to filter out disabled companies after deletion.

Returns: {"deleted": True, "company_id": ..., "response": ...}.

Inputs: company_id (required), account_id. Returns: result

delete_notificationA
DestructiveIdempotent

Delete a notification rule. The rule is gone. To keep but mute it, prefer update_notification(send_email=False, send_desktop=False, send_push=False).

Args: notification_id: Notification rule ID. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string {"deleted": True, "notification_id": ..., "response": ...}. The response mirrors CallRail's body (often empty on 204).

Inputs: notification_id (required), account_id. Returns: result

delete_tagA
DestructiveIdempotent

Delete a tag definition from the account. Removes it from any calls or form submissions that had it applied.

This is a HARD delete; the tag is gone permanently along with its historical applications. To preserve history, prefer renaming or disabling via update_tag instead.

Args: tag_id: Numeric tag ID. CallRail tag IDs are integers (NOT the string-prefixed format other entities use). Must match ^[0-9]+$ (string or numeric forms accepted). account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string {"deleted": True, "tag_id": ...} on success.

Inputs: tag_id (required), account_id. Returns: result

delete_trackerA
DestructiveIdempotent

Delete (disable) a tracker. Soft-removes it from active trackers; the tracker keeps its call history but stops receiving new calls. The underlying phone number is released.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted.

Returns: An object with deleted: True, tracker_id, and response (CallRail's body, which on success contains the disabled tracker record including disabled_at timestamp). Empty object if CallRail returned 204.

Inputs: tracker_id (required), account_id. Returns: result

delete_userB
DestructiveIdempotent

Remove a user from the account.

CallRail's DELETE on users is typically a hard-remove (unlike companies/trackers which soft-delete). The user loses access immediately.

Returns: {"deleted": True, "user_id": ..., "response": ...}.

Inputs: user_id (required), account_id. Returns: result

form_statsA
Read-onlyIdempotent

Server-side form-submission totals via /forms/summary.json.

Args: days: Lookback (default 30). Ignored if start_date given. start_date / end_date: 'YYYY-MM-DD'. Explicit dates win. company_id: Filter to one company. account_id: Auto-resolves if omitted.

Returns: JSON string with start_date, end_date, time_zone, and total_results (e.g. {"total_forms": N}).

group_by ('source' | 'keywords' | 'campaign' | 'referrer' | 'landing_page' | 'form_name' | 'company') returns grouped_results; fields (comma-separated) selects additional summary fields; lead_status, tags and time_zone filter as on call_stats.

Inputs: days, tags, fields, end_date, +6 more. Returns: result

get_callA
Read-onlyIdempotent

Get full detail for a specific call.

Args: call_id: CallRail call id (prefix 'CAL...'). account_id: Auto-resolves if omitted. fields: Comma-separated extra fields (see list_calls for common names).

Inputs: call_id (required), fields, account_id. Returns: result

get_call_page_viewsA
Read-onlyIdempotent

Get the visitor's page-view history behind a call: which pages they browsed (with timestamps) before and around dialing. Pairs with call_eligibility_check for conversion debugging: shows the actual session journey that led to the call.

Args: call_id: 'CAL...' id. account_id: Auto-resolves if omitted. per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with page_views[] (paginated).

Only available for calls placed to session trackers (a CallRail restriction). time_zone (IANA) localizes the timestamps.

Inputs: call_id (required), page, per_page, time_zone, +1 more. Returns: result

get_call_recordingA
Read-onlyIdempotent

Get the recording URL for a call. CallRail documents the link as good for at least 24 hours but not guaranteed forever; HIPAA accounts receive a temporary URL that expires in about 24 hours. Play or download it promptly rather than storing the link.

Recording must be enabled on the company (CallRail UI > Settings > Account). Calls placed BEFORE recording was enabled have no recording even if it's enabled now; CallRail does not retroactively record.

Args: call_id: 'CAL...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with url (audio URL, typically MP3) plus recording metadata. Empty url typically means recording was disabled at call time, or the user opted out via the call-flow recording disclaimer.

Inputs: call_id (required), account_id. Returns: result

get_call_transcriptA
Read-onlyIdempotent

Get the transcript and conversation-intelligence fields for a call.

Requests the documented field selection on GET /calls/{id}.json (transcription, conversational_transcript, call_summary, call_highlights, keywords_spotted, sentiment, speaker_percent) and falls back to the older /calls/{id}/transcription.json endpoint when those fields come back empty.

Requires CallRail Conversation Intelligence (CallScribe) to have been enabled on the company at the time of the call; CallRail does not retroactively transcribe. Since CallRail's 2026-05-21 API change the transcript fields return null without a Premium Conversation Intelligence subscription even when a transcript exists in the UI, so an empty result is reported with a hint that names both causes.

Args: call_id: 'CAL...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with id plus whichever of the fields above CallRail returned (conversational_transcript is a list of {speaker, phrase, start} turns).

Inputs: call_id (required), account_id. Returns: result

get_companyA
Read-onlyIdempotent

Get full detail for one company.

Args: company_id: 'COM...' id. account_id: Auto-resolves if omitted. fields: Optional attributes (comma-separated), for example 'verified_caller_ids'.

Note: Returns the disabled record (with status: "disabled", disabled_at timestamp) for soft-deleted companies, NOT 404. Check the status field if you need to distinguish.

Inputs: company_id (required), fields, account_id. Returns: result

get_form_submissionA
Read-onlyIdempotent

Get full detail for one form submission, including all submitted field data.

Useful for retrieving the original form payload after seeing a submission ID via list_form_submissions or in a webhook callback.

Args: submission_id: 'FOR...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the form submission: submitted_at, customer details, source/UTM attribution, landing page URL, referrer, and form_data dict keyed by form field name.

Inputs: submission_id (required), account_id. Returns: result

get_integrationA
Read-onlyIdempotent

Get full detail for one integration.

Args: integration_id: Numeric integration id (from list_integrations). account_id: Auto-resolves if omitted. fields: Optional attributes (comma-separated).

Inputs: integration_id (required), fields, account_id. Returns: result

get_lead_timelineA
Read-onlyIdempotent

Get a lead's full cross-channel activity timeline: every call, form submission, and text thread from that person in one response, with first-touch/last-touch attribution.

This replaces the manual "search calls by number + search forms by email" dance when reconstructing a customer's history.

Args: lead_id: 'PER...' lead id (from list_leads). account_id: Auto-resolves if omitted. per_page: Timeline page size (max 250). page: 1-indexed.

Returns: JSON string with lead (the person record) and timeline[] (chronological interaction entries, paginated).

Inputs: lead_id (required), page, per_page, account_id. Returns: result

get_sms_threadA
Read-onlyIdempotent

Get one SMS thread's lead-management record (notes, value, tags, lead_qualification, state). For the message transcript itself use get_text_message with the conversation id.

Args: thread_id: Thread id (from list_sms_threads). account_id: Auto-resolves if omitted.

Inputs: thread_id (required), account_id. Returns: result

get_tagB
Read-onlyIdempotent

Get full detail for one tag.

Args: tag_id: Numeric tag id. account_id: Auto-resolves if omitted.

Inputs: tag_id (required), account_id. Returns: result

get_text_messageA
Read-onlyIdempotent

Get full detail for one SMS conversation, including all messages.

Args: conversation_id: Short alphanumeric conversation id (e.g. '8hw3p'). Returned by list_text_messages as id on each conversation.

Inputs: conversation_id (required), account_id. Returns: result

get_trackerC
Read-onlyIdempotent

Get full detail for a specific tracker.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted.

Inputs: tracker_id (required), account_id. Returns: result

get_userA
Read-onlyIdempotent

Get full detail for one user on the account.

Args: user_id: 'USR...' id. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the user object: id, email, first_name, last_name, role ('admin' | 'manager' | 'reporting'), accepted_at (null if invitation pending), time_zone, and company_ids[] the user can access.

Inputs: user_id (required), account_id. Returns: result

list_accountsA
Read-onlyIdempotent

List CallRail accounts accessible to this API key.

Most users have one account per agency. The returned id is used as account_id in all other tools (auto-resolved if omitted, or pinned with the CALLRAIL_ACCOUNT_ID environment variable). fields (comma-separated) adds optional attributes such as 'numeric_id', the number shown in CallRail app URLs.

Inputs: fields. Returns: result

list_callsA
Read-onlyIdempotent

List calls. Paginated. Filterable by company, date window, and answer status.

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. Omit for all companies. days: Lookback in days (default 7). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today). answer_status: Server-side filter. One of 'answered', 'missed', 'voicemail'. This is CallRail's real filter parameter. Note that 'missed' includes calls that reached voicemail (CallRail's own definition) and 'voicemail' selects only that subset. answered: DEPRECATED alias kept for backwards compatibility. 'true' maps to answer_status='answered', 'false' to 'missed'. (CallRail has no answered query param; passing it used to be silently ignored, so results were unfiltered.) source: CallRail has NO server-side source filter, so this is applied CLIENT-SIDE to the current page only: the calls array is filtered by exact, case-insensitive match on each call's source field. total_records/total_pages in the response still describe the UNFILTERED query. See source_filter in the response for what was actually applied. For source breakdowns prefer call_stats(group_by='source'). per_page: Max 250. page: 1-indexed. fields: Comma-separated additional fields to include, e.g. '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'.

Server-side filters (documented, live-verified 2026-10-05): search matches business_phone_number, customer_name, customer_number, note, source and tracking_phone_number (any fragment of a phone number works); direction ('inbound' | 'outbound'); device ('desktop' | 'mobile'); call_type ('first_call' | 'missed' | 'abandoned' | 'voicemails' | 'inbound' | 'outbound' | 'voice_assist' | 'all'); lead_status ('good_lead' | 'not_a_lead' | 'not_scored'); tracker_id; tags (calls carrying ANY of the listed tag names); sort (a call field such as 'start_time', 'duration' or 'customer_name') with order ('asc' | 'desc'). time_zone (IANA) sets the day boundaries CallRail applies to the window and is also used to compute "today" for days; without it CallRail uses the API key owner's time zone.

Inputs: days, page, sort, tags, +17 more. Returns: result

list_companiesA
Read-onlyIdempotent

List companies (client businesses) under a CallRail account.

Args: account_id: CallRail account ID. Auto-resolves if omitted. per_page: Page size (max 250). status: Filter by status. Defaults to None (returns all). Common values: 'active' (excludes disabled/soft-deleted), 'disabled'. page: 1-indexed. Agencies with more than per_page companies need this to reach the rest. Previously there was no way to fetch page 2 via this tool.

search matches the company name; fields (comma-separated) adds optional attributes, for example 'verified_caller_ids' (the readable list of outbound caller IDs, which the caller_ids endpoint itself gates behind a permission).

Inputs: page, fields, search, status, +2 more. Returns: result

list_form_submissionsA
Read-onlyIdempotent

List form submissions captured by CallRail's Form Tracking. Paginated. Filterable by company and date window.

Args: account_id: CallRail account ID. Auto-resolves if omitted. company_id: Filter to one company. Omit for all companies. days: Lookback in days (default 7). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today). per_page: Page size (max 250). page: 1-indexed. fields: Comma-separated additional fields to include, e.g. 'company_name,form_data,referrer,landing_page_url,source, utm_source,utm_medium,utm_campaign,utm_content,utm_term, gclid,fbclid,form_url,form_name'.

Returns: JSON string with page, per_page, total_pages, total_records, and form_submissions[]. Each submission has id ('FOR...'), submitted_at, customer details (if captured), and a form_data dict keyed by form field name.

Filters: lead_status ('good_lead' | 'not_a_lead' | 'not_scored'), tags (any of), person_lead (only submissions linked to a lead), sort ('submitted_at' | 'form_url'; 'created_at' is being deprecated by CallRail) with order ('asc' | 'desc'), and time_zone (IANA). Requires form tracking to be enabled on at least one company; otherwise CallRail returns 403 (the error carries a hint).

Inputs: days, page, sort, tags, +10 more. Returns: result

list_integrationsA
Read-onlyIdempotent

List integrations attached to one company (GMB, Google Ads, Facebook, Slack, Webhooks, etc.).

Args: company_id: 'COM...' id. Required: the integrations endpoint returns 400 without it (account-level listing isn't supported). per_page: Page size (max 250). page: 1-indexed. account_id: Auto-resolves if omitted.

fields (comma-separated) adds optional attributes to each integration.

Inputs: company_id (required), page, fields, per_page, +1 more. Returns: result

list_leadsA
Read-onlyIdempotent

List leads (unique people) across calls, forms, and texts.

A lead is CallRail's deduplicated person record: one entry per customer regardless of how many times they called / submitted / texted. Use get_lead_timeline for a lead's full cross-channel history.

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with page, per_page, total_pages, total_records, and leads[]. Each lead has id ('PER...'), name, phone, email, company_id, company_name, created_at.

sort ('created_at' | 'name' | 'email') with order ('asc' | 'desc').

Inputs: page, sort, order, per_page, +2 more. Returns: result

list_notificationsA
Read-onlyIdempotent

List notification rules on the account.

Args: company_id: Applied CLIENT-SIDE (CallRail ignores it as a query param). Keeps rules scoped to that company plus account-wide rules (company_id null), which also fire for it. The page's total_records describes the unfiltered query; see company_filter in the response. user_id: Server-side filter on the notified user. notification_type: Server-side filter: 'push', 'email', or 'desktop'. email: Server-side filter on an email-only recipient. per_page: Page size (max 250). page: 1-indexed. account_id: Auto-resolves if omitted.

Inputs: page, email, user_id, per_page, +3 more. Returns: result

list_sms_threadsA
Read-onlyIdempotent

List SMS threads. Unlike list_text_messages (conversation transcripts), threads carry the lead-management surface: notes, value, tags, lead_qualification, state. Threads are UPDATABLE via update_sms_thread.

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with sms_threads[]. Each thread has id, customer_name / customer_phone_number, current + initial tracker/tracking-number, notes, value, tags, lead_qualification, state.

days / start_date / end_date window the threads (CallRail wants start and end together, so a lone start_date is paired with today); search matches phone number, name and tag name.

Inputs: days, page, search, end_date, +4 more. Returns: result

list_tagsA
Read-onlyIdempotent

List all tags in the account, or filtered to one company.

status ('enabled' | 'disabled') and tag_level ('account' | 'company') filter server-side.

Inputs: page, status, per_page, tag_level, +2 more. Returns: result

list_text_messagesA
Read-onlyIdempotent

List SMS/text message conversations sent to or received via CallRail trackers. Paginated. Filterable by company and date window.

Receiving SMS works on standard accounts. Outbound SMS sending requires CallRail's A2P SMS API permission (returns 403 otherwise); see create_text_message notes if available on your plan.

Args: account_id: CallRail account ID. Auto-resolves if omitted. company_id: Filter to one company. Omit for all companies. days: Lookback in days (default 7). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today). per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with page, per_page, total_pages, total_records, and conversations[]. Each conversation has a list of inbound + outbound messages, customer phone number, the tracking number used, and timestamps.

Inputs: days, page, end_date, per_page, +3 more. Returns: result

list_trackersA
Read-onlyIdempotent

List tracking phone numbers (trackers). Each tracker maps a pool of phone numbers to a traffic source (Google Ads, Organic, Direct, etc.).

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. per_page: Page size (max 250). page: 1-indexed. status: Filter by status. Defaults to None (returns all, including soft-deleted/disabled). Common values: 'active', 'disabled'.

type ('source' | 'session') filters by tracker kind; search matches the tracker name; fields (comma-separated) adds optional attributes.

Inputs: page, type, fields, search, +4 more. Returns: result

list_usersA
Read-onlyIdempotent

List users on the account. Paginated.

Args: account_id: CallRail account ID. Auto-resolves if omitted. company_id: Only users with access to this company. search: Matches first_name, last_name and email. sort: User field to sort by, with order ('asc' | 'desc'). per_page: Page size (max 250). page: 1-indexed.

Returns: JSON string with users[]. Each user has id ('USR...'), email, first_name, last_name, name, role ('admin' | 'manager' | 'reporting'), accepted (whether the invitation was accepted) and companies[] ({id, name}) the user can access.

Inputs: page, sort, order, search, +3 more. Returns: result

remove_call_tagsB
Idempotent

Remove specific tags from a call (case-sensitive on tag name).

Idempotent: removing a tag that isn't attached succeeds silently. Empty/whitespace-only entries in the input list are ignored.

Inputs: tags (required), call_id (required), account_id. Returns: result

search_calls_by_numberA
Read-onlyIdempotent

Find calls from/to a specific phone number. Matches on the last 10 digits of the stored customer_phone_number so any format works.

Args: phone_number: Any format, normalized to digits-only. Must contain at least 7 digits to avoid false positives. account_id: Auto-resolves. company_id: Optional company filter. days: Lookback window (default 90).

Inputs: phone_number (required), days, account_id, company_id. Returns: result

spam_detectorA
Idempotent

Heuristically identify likely-spam calls and (optionally) tag them.

Spam scoring (additive): +2 if duration < 10 seconds +1 if not answered +1 if first_call AND duration < 30 seconds +1 if same caller appears >=3 times in window (likely auto-dialer) A call scoring >= 3 is flagged as likely spam.

Args: company_id: Restrict to one company (recommended). days: Lookback window (1-90; 90 is hard-capped to avoid memory blowup on high-volume clients: full call list is materialized for scoring before truncating the response). auto_tag: If True, ADD tag_name to each likely-spam call after the scan. Default False (preview only). Note: we deliberately do NOT mark calls as spam=True automatically: CallRail HIDES spam-flagged calls from default GET endpoints, so self-reviewing them later becomes painful. Tag first, manually spam-flag if confirmed. tag_name: The tag to add when auto_tag=True. Default 'auto_detected_spam'. Auto-creates the tag at company level if it doesn't exist (CallRail's behavior). account_id: Auto-resolves if omitted.

Returns: - score breakdown by call - histogram of caller phone numbers (so you can spot a single dialer hammering you) - if auto_tag: count tagged + failures

Inputs: days, auto_tag, tag_name, account_id, +1 more. Returns: result

update_callA
Idempotent

Update an existing call: notes, tags, spam flag, customer name, lead status.

Args: call_id: 'CAL...' id of the call to update. account_id: Auto-resolves if omitted. note: Replace the call's note text. tags: REPLACE the call's tag list with this set of tag names. (Use add_call_tags/remove_call_tags for additive changes.) spam: True to mark as spam. False is rejected: CallRail cannot un-mark spam via the API. Note: spam-flagged calls are HIDDEN from default GET endpoints; re-reads will 404. Tag the call BEFORE flagging spam if you need both. customer_name: Override the auto-detected caller name. lead_status: 'good_lead' or 'not_a_lead'. CallRail returns 400 when a call already at previously_marked_good_lead is set to good_lead.

Note: value is intentionally NOT exposed here. CallRail's API returns a 500 server error when value is included in the PUT body to /calls (verified via live testing 2026-04-24). It IS supported on form submissions. See update_form_submission.

Empty-string fields (e.g. note="") are rejected because CallRail interprets them as "clear this field", which is almost always a mistake. To intentionally clear a field, set it to None and use a separate UI operation, or contact CallRail support.

Length caps (rejected pre-network): - note: 4000 chars - customer_name: 200 chars - tags: 100 entries max

Inputs: call_id (required), note, spam, tags, +3 more. Returns: result

update_companyA
Idempotent

Update mutable settings on a company. Pass None to leave a field unchanged; only fields with explicit values are sent in the PUT body.

CRITICAL: Any boolean toggle you set will OVERRIDE current state. If a company has CallScribe enabled and you call update_company(name='New Name') without passing callscribe_enabled, CallScribe stays on. But passing callscribe_enabled=False will DISABLE CallScribe (a paid feature). Be deliberate with bool args.

Empty-string name / time_zone are rejected (almost always a mistake; pass None to leave them alone).

Args: company_id: 'COM...' id. name: New display name. Empty string rejected. Max 255 chars. time_zone: IANA tz string (e.g. 'America/New_York'). callscore_enabled: CallScore AI lead scoring. PAID add-on. lead_scoring_enabled: NOT settable via the API (read-only field); passing it returns an error. Toggle it in the CallRail UI. swap_exclude_jquery: Deprecated by CallRail, has no effect. Not sent; reported under api_warnings in the response. callscribe_enabled: Conversation Intelligence (transcripts + call highlights). PAID feature. keyword_spotting_enabled: Deprecated by CallRail, has no effect. Not sent; reported under api_warnings in the response. form_capture: Enable CallRail Form Tracking on this company. Sent as CallRail's external_form_capture PUT field. swap_ppc_override: Override the original source when a visitor arrives via PPC. swap_landing_override: Landing-page URL parameter (for example 'utm_source') that overrides the original source. Pass "" to turn the override off (sent as null). swap_cookie_duration: Visitor cookie lifetime, with swap_cookie_duration_unit ('months' | 'weeks' | 'days'). CallRail caps it at 6 months. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated company object, plus api_warnings when a deprecated no-op field was dropped.

Inputs: company_id (required), name, time_zone, account_id, +10 more. Returns: result

update_form_submissionA
Idempotent

Update an existing form submission: note, tags, value, lead status.

Args: submission_id: CallRail form-submission id (prefix 'FOR...'). account_id: Auto-resolves if omitted. note: Free text (max 4000 chars). tags: Tag names. REPLACES the submission's tags unless append_tags=True (CallRail's documented flag). Unknown names are auto-created at the company level. value: Monetary value; sent as a currency string ("12.50"), which is what PUT /form_submissions accepts. spam: NOT supported for form submissions (the PUT body has no spam field); passing it returns an error. Spam flagging exists for calls only (update_call). lead_status: 'good_lead' or 'not_a_lead'. CallRail returns 400 when a submission already at previously_marked_good_lead is set to good_lead. append_tags: Add tags to the existing ones instead of replacing.

Empty-string fields (e.g. note="") are rejected to prevent accidental field-clearing. See update_call docstring.

Length caps (rejected pre-network): - note: 4000 chars - tags: 100 entries max

Inputs: submission_id (required), note, spam, tags, +4 more. Returns: result

update_notificationA
Idempotent

Update a notification rule. Pass None to leave a field unchanged; only fields with explicit values are sent in the PUT body.

Notification rules trigger emails / desktop pushes / SMS when calls or form submissions match conditions. Use this to rewire targets, change triggering events, or silence a noisy rule without deleting it (set all send_* to False).

Args: notification_id: Notification rule ID. name: NOT updatable (CallRail generates it). Ignored and reported under api_warnings. alert_type: 'all', 'first_call', 'missed_and_vm' or 'vm_only' (CallRail rejects the older vocabulary). Unknown values warn but are passed through. send_email: Send email notification. send_desktop: Send desktop browser push. send_push: Send mobile push notification. call_enabled: Trigger on call events. sms_enabled: Trigger on SMS events. email: NOT updatable (an email-only recipient is fixed when the rule is created). Ignored and reported under api_warnings. company_id / tracker_id: Re-scope the rule. account_id: CallRail account ID. Auto-resolves if omitted.

Returns: JSON string with the updated notification rule, plus api_warnings when name or email was ignored.

Inputs: notification_id (required), name, email, send_push, +8 more. Returns: result

update_sms_threadA
Idempotent

Update an SMS thread's lead-management fields. This is the texting equivalent of update_call. Closes the gap where texting leads couldn't be tagged / noted / qualified via API.

Args: thread_id: Thread id (from list_sms_threads). notes: Note text (max 4000 chars). Empty string rejected. value: Monetary value; sent as a currency string ("12.50"), which is what PUT /sms-threads accepts. tags: Tag names to apply (max 100). append_tags: If True (default), tags are ADDED to existing ones (CallRail's append_tags flag). If False, tags REPLACES the thread's tag list. lead_qualification: 'good_lead' or 'not_a_lead' (CallRail docs; null clears it, which this tool does not expose). account_id: Auto-resolves if omitted.

Inputs: thread_id (required), tags, notes, value, +3 more. Returns: result

update_tagA
Idempotent

Rename, recolor, disable or re-enable a tag.

Args: tag_id: Numeric tag id. account_id: Auto-resolves if omitted. name: New display name (changes the tag everywhere it is applied). disabled: True hides the tag from new interactions (existing applications stay); False re-enables it. color: One of the 24 CallRail-supported colors (see VALID_TAG_COLORS): gray1-2, blue1-2, cyan1-2, purple1-2, pink1-4, red1-2, orange1-4, yellow1-2, green1-4.

Inputs: tag_id (required), name, color, disabled, +1 more. Returns: result

update_trackerA
Idempotent

Update a tracker's mutable settings: name, whisper, SMS, swap targets, campaign name, and the basic call flow (destination, recording, greeting).

CallRail's PUT /trackers replaces the entire call_flow object, so when any call-flow field is given this tool first reads the tracker and merges the change into its current basic flow; the destination, recording flag and greeting you did not mention are preserved. Trackers on an advanced call flow (IVR menus, schedules, voicemail steps) are refused for call-flow edits because the API could only replace that flow with a basic one.

Args: tracker_id: 'TRK...' id. account_id: Auto-resolves if omitted. name: New display name. destination_number: Where calls forward (e.g. "+14129548337"). whisper_message: New whisper text (max 500 chars). greeting_text: New text-to-speech greeting (max 500 chars). sms_enabled: Toggle SMS on/off. recording_enabled: Toggle call recording for this tracker. greeting_recording_url: http(s) URL of a .wav/.mp3 greeting. CallRail copies the file once; greeting_text is cleared so the recording takes effect (pass one or the other, not both). swap_targets: Phone numbers on the website that this tracker's number replaces (any formatting). Replaces the current list. campaign_name: Campaign label for reports. Source trackers only.

Field-level rules: - name, destination_number, whisper_message, greeting_text must be non-empty strings if provided. Pass None (the default) to leave a field unchanged.

NOTE: Setting status via this PUT is silently ignored by CallRail. To disable a tracker, use delete_tracker(tracker_id) (soft-delete / disabled, keeps history). To permanently remove, contact CallRail support.

Inputs: tracker_id (required), name, account_id, sms_enabled, +7 more. Returns: result

update_userA
Idempotent

Update a user's name or company access. Pass None to leave unchanged.

CallRail's PUT /users accepts first_name, last_name, email and companies only, with two documented restrictions: names and email can be changed only for the user who owns the API key, and an email change requires that user's current password in the request. This server never handles passwords, so email is rejected; role is rejected because the API has no way to change it (recreate the user, or use the CallRail UI). Updates are only accepted for users who have accepted their invitation.

Args: user_id: 'USR...' id. first_name, last_name: Only for the API key's own user. email: Rejected (see above). role: Rejected (see above). company_ids: REPLACES the user's company access list (send the full list the user should keep). Admin-only; applies to manager and reporting users.

Inputs: user_id (required), role, email, last_name, +3 more. Returns: result

usage_summaryA
Read-onlyIdempotent

Per-company cost-attribution summary for the current cycle.

Aggregates active trackers + per-company call minutes and projects what each client is contributing to the agency's CallRail bill. Useful for:

  • Deciding which client to renegotiate / upsell / drop

  • Sanity-checking the upcoming invoice

  • Quarterly reviews

Pricing assumes Call Tracking Starter ($50 base + 5 numbers + 250 mins bundled; $3/local number, $5/toll-free number, $0.05/local minute, $0.08/toll-free minute over bundle). Edit PRICING_* constants in server.py if you're on a different plan.

Args: account_id: Auto-resolves if omitted. days: Lookback window in days (default 30 = roughly one cycle). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today).

Returns: - agency: plan + totals + bundle utilization + cycle estimate - by_company[]: each company's minutes, active numbers, cost share (sorted by cost-share descending) - biggest_cost_driver: name of top company - partial_failures[]: per-company API errors. Each entry carries partial_calls_before_failure, partial_minutes_before_failure, partial_local_numbers, partial_tollfree_numbers so an under- reporting agency_total is observable, not silent. - notes: caveats about the cost model (toll-free minute pricing not yet differentiated; SMS not included).

Cost shares sum exactly to agency.estimated_cycle_total via largest- remainder rounding.

Inputs: days, end_date, account_id, start_date. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 57 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions, with separate CRUD surfaces for companies, trackers, users, tags, notifications, calls, forms, and SMS threads. There is some overlap among call analytics tools (call_summary, call_stats, call_timeseries) and between SMS transcript vs SMS thread tools, but the descriptions explicitly explain their boundaries.

    Naming Consistency4/5

    The set is predominantly consistent snake_case, usually verb_noun (list_calls, create_tracker, update_form_submission, delete_notification). A notable minority use noun-based or analysis-oriented names (call_stats, usage_summary, spam_detector, compare_periods), but casing remains consistent and the names are still readable.

    Tool Count2/5

    57 tools is very heavy for a single MCP surface and increases the chance of misselection or context overload. CallRail is a broad platform, so the tools are not arbitrary, but several adjacent analytics and read helpers push the set well beyond a well-scoped range.

    Completeness4/5

    Coverage is broad: companies, trackers, calls, forms, users, tags, notifications, leads, stats, and billing/usage are mostly covered with full lifecycle operations. Minor gaps remain, such as no visible SMS send/create tool despite SMS thread read/update support, limited integration write operations, and no get_notification tool.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol implementation for the HubSpot API that provides a standardized interface for accessing and managing CRM data, including companies, contacts, deals, and other objects with comprehensive CRUD operations and association management.
      62 npm
      35
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables comprehensive integration with Kommo CRM through 25 tools for managing leads, contacts, companies, tasks, events, and generating detailed analytics reports. Supports advanced workflow management, pipeline operations, and real-time performance tracking.
      22
      16
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude to retrieve and analyze Google Analytics 4 data through 20+ analysis tools, providing insights on traffic, user behavior, conversions, and engagement metrics in Japanese-formatted output.
      20
      2
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables comprehensive management of Google Ads accounts by allowing users to create campaigns, manage keywords, and generate performance reports through a context-aware interface. It features a three-layer architecture that integrates product knowledge and historical campaign data to support intelligent decision-making.
      MIT