CallRail MCP
CallRail MCP exposes a broad set of CallRail REST API v3 tools for querying, managing, provisioning, and analyzing call-tracking data through an MCP client.
List accounts, companies, trackers, calls, form submissions, text messages, users, tags, notifications, integrations, leads, and SMS threads.
Retrieve detailed records for calls, trackers, companies, users, forms, text conversations, tags, integrations, and SMS threads.
Search calls by phone number and inspect call recordings, transcripts, page-view journeys, and Google Ads conversion eligibility.
Summarize calls and analyze call volume over time; run server-side call/form aggregations and grouped statistics.
Run agency cost-attribution reports, compare periods, identify spam-like calls, and bulk-update calls with dry-run safety.
Update calls, form submissions, tags, SMS threads, companies, users, trackers, and notification rules.
Create companies, users, tags, form submissions, notifications, and outbound calls.
Provision new trackers with
confirm_billing=Trueas a cost-safety guard.Delete/soft-delete trackers, companies, users, tags, and notifications.
Filter and paginate results, request additional fields, and auto-resolve or pin the CallRail account.
Use safety guards including
confirm_billing,confirm_dialing, anddry_rundefaults for risky operations.
Allows querying Facebook integration details attached to a company.
Allows querying Google Ads integration details and checking call conversion eligibility for Google Ads.
Allows querying Slack integration details attached to a company.
callrail-mcp
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-mcpTo install from source (latest unreleased):
pipx install git+https://github.com/pghdma/callrail-mcp.gitAuth
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.txtOr 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 accessible CallRail accounts. |
| List companies (clients) under an account. Optional |
| List tracking phone numbers and their source mapping. Optional |
| Full detail for one tracker |
| Paginated call list. Filter by company, date window, |
| Full detail for a specific call |
| Aggregate stats (total, answered by a person, voicemail, missed, by disposition, by source, duration) for a window |
| CallRail Form Tracking submissions. Filter by |
| SMS conversations |
| Account users, paginated. Filter by |
| 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 |
| Transcript plus |
| Find calls by phone number across a window (narrowed server-side with |
| List tags in an account or filtered to one company. Filter by |
Write tools
Tool | Purpose |
| Update note, tags, spam flag, customer name, lead status |
| Additive and subtractive tag changes (preserves existing) |
| Note, tags (replace, or add with |
| Full CRUD on company-level and account-level ( |
Tracker provisioning
Tool | Purpose |
| Provision a new tracking number. Requires |
| 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 |
| Soft-delete a tracker (releases the phone number, preserves history) |
Account management
Tool | Purpose |
| 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 |
| Full user CRUD. |
| Single tag detail |
| Single form-submission detail |
| Single SMS conversation with all messages |
| Manually create a form submission (backfill walk-in, paper-form, or offline leads). Requires |
Notifications and integrations
Tool | Purpose |
| Full per-user alert-rule CRUD (who gets pinged on which call, text, or form event) |
| 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 |
| Place an outbound call. CallRail dials |
Leads and server-side analytics
Tool | Purpose |
| CallRail's deduplicated person records (sortable by |
| 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 |
| Server-side call aggregation via |
| Call-volume trend line. Supports |
| Server-side form-submission totals. |
| The visitor's page-view journey behind a call. Pairs with |
Agency aggregation
Tool | Purpose |
| 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" |
| Audit whether a specific call qualifies as a Google Ads conversion. Checks |
| Compare the current N-day window against the previous one. Per-company minute and call deltas plus biggest mover |
| Apply one update (tag, note, lead_status, spam) to every call matching a filter. |
| Heuristically flag likely-spam calls (short duration, unanswered, repeat-caller patterns). Optional |
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_statusis the documented filter and is applied server-side.answeredremains as a deprecated alias that translates toanswer_status.sourceis applied client-side, and the response includes asource_filterblock stating exactly what was matched. For source breakdowns, prefercall_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_checkandbulk_update_callstreat a call as answered only when a person answered (answeredand notvoicemail) and report voicemail separately. Since v1.3.2 they use CallRail'scall_dispositionfield when it is present, which also separates abandoned and Voice Assist calls.answer_status=missedincludes voicemail.No date window means CallRail's
recentrange, the previous 7 days including today, not all time. Windowed tools accept an IANAtime_zoneso day boundaries match the client's reporting zone, andusage_summary/compare_periodsforward 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_domainConversation-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 |
| 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 |
| Not offered |
Safety guards |
| 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.jsonwithtype=Webhook) needs Integration-Admin permission.Outbound Caller IDs (
/caller_ids.jsonCRUD) is documented by CallRail but returns 403 on a standard account.Message Flows (
/message-flows.jsonCRUD, SMS auto-reply flows) is documented but returns 403.Integration Filters (
/integration_triggers.jsonCRUD) 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_mcpThe 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]"
pytestSee 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 toolsadd_call_tagsAIdempotent
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_callsADestructive
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_checkARead-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:
Did the call have a
gclid? (Required for CallRail to upload to Google Ads as a UPLOAD_CLICKS Phone Call conversion.)Was the call answered? (Most integrations skip unanswered.)
Did duration meet Google Ads' minimum? (Default 60s; configurable per conversion action in Google Ads UI.)
Is the call from a Google source? Detection uses CallRail's internal
sourceslug (e.g.google_paid,google_my_business)presence of gclid, NOT the user-editable
source_namedisplay 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_statsARead-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_summaryARead-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_timeseriesARead-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_periodsARead-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_companyADestructiveIdempotent
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_notificationADestructiveIdempotent
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_tagADestructiveIdempotent
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_trackerADestructiveIdempotent
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_userBDestructiveIdempotent
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_statsARead-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_callARead-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_viewsARead-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_recordingARead-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_transcriptARead-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_companyARead-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_submissionARead-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_integrationARead-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_timelineARead-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_threadARead-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_tagBRead-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_messageARead-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_trackerCRead-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_userARead-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_accountsARead-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_callsARead-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_companiesARead-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_submissionsARead-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_integrationsARead-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_leadsARead-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_notificationsARead-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_threadsARead-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_tagsARead-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_messagesARead-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_trackersARead-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_usersARead-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_tagsBIdempotent
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_numberARead-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_detectorAIdempotent
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_callAIdempotent
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_companyAIdempotent
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_submissionAIdempotent
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_notificationAIdempotent
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_threadAIdempotent
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_tagAIdempotent
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_trackerAIdempotent
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_userAIdempotent
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_summaryARead-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
Scored across 57 tools
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.
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.
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.
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
Related MCP Connectors
40+ Lightning-paid AI tools for agents: calls, SMS, fax, voice, translation. No signup, no keys.
Read calls, contacts, users, teams and numbers; tag calls and create or update contacts.
Hundreds of pay-per-call tools for agents: company records, screening, validation, web reading.
34-tool GTM gateway: CRMs, ad platforms, analytics, Google Workspace, AWS, and LLM orchestration.
Related MCP Servers
- AlicenseCqualityDmaintenanceA 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 npm35MIT
- AlicenseBqualityBmaintenanceEnables 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.2216MIT
- AlicenseAqualityDmaintenanceEnables 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.202MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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