ctm-multi-mcp — Multi-account CTM data extraction

A read-only Model Context Protocol (MCP) server for extracting data across multiple CallTrackingMetrics sub-accounts using a single parent/reseller API key.

Built for resellers and agencies managing multiple CTM accounts who need to pull call data, reports, number inventory, contacts, sources, and configuration into custom Claude bots.

How It Works

1. Auto-discovery — On startup, the server uses the parent API key to list all sub-accounts automatically. No manual configuration needed.

2. Filtering — Optionally limit which accounts are queried via env var or a JSON config file with optional labels.

3. Cross-account tools — Every tool runs across all (or selected) accounts and returns results with account attribution. One failing account doesn't block the rest.

4. Read-only — No write tools. Safe for analysis, reporting, and data extraction without risk of modifying production config.

Related MCP server: meta-mcp

Install

Not yet published to PyPI — install from source for now:

git clone https://github.com/CTMJSON/ctm-multi-mcp
cd ctm-multi-mcp
python3 -m venv .venv
./.venv/bin/pip install -e .

This installs a ctm-multi-mcp executable at .venv/bin/ctm-multi-mcp inside the cloned folder — use that full path when connecting a Claude client below.

Once published, install will be:

pip install ctm-multi-mcp
# or, with no install, via uv:
uvx ctm-multi-mcp

Configuration

Filtering sub-accounts

To limit which accounts the server queries, set CTM_ACCOUNT_IDS:

export CTM_ACCOUNT_IDS=12345,67890,11111

Or create ~/.ctm-accounts.json:

{
  "account_ids": ["12345", "67890", "11111"],
  "labels": {
    "12345": "Client A (Enterprise)",
    "67890": "Client B (SMB)"
  }
}

Labels appear in tool output for easy identification. If neither filter is set, all sub-accounts discoverable by the parent key are included.

Connecting to Claude Desktop

Edit your Claude Desktop config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json). If the file doesn't exist yet, create it with a mcpServers block and add an entry for ctm-multi-mcp. Use the full path to the ctm-multi-mcp executable from the Install step:

{
  "mcpServers": {
    "ctm-multi-mcp": {
      "command": "/absolute/path/to/ctm-multi-mcp/.venv/bin/ctm-multi-mcp",
      "env": {
        "CTM_BASIC_AUTH": "<base64 access_key:secret_key>"
      }
    }
  }
}

Restart Claude Desktop for the change to take effect. To limit which accounts are queried, add "CTM_ACCOUNT_IDS": "12345,67890,11111" to env.

Connecting to Claude Code

claude mcp add ctm-multi-mcp \
  --env CTM_BASIC_AUTH="<base64 access_key:secret_key>" \
  -- /absolute/path/to/ctm-multi-mcp/.venv/bin/ctm-multi-mcp

With account filtering:

claude mcp add ctm-multi-mcp \
  --env CTM_BASIC_AUTH="<base64 access_key:secret_key>" \
  --env CTM_ACCOUNT_IDS=12345,67890,11111 \
  -- /absolute/path/to/ctm-multi-mcp/.venv/bin/ctm-multi-mcp

Once published to PyPI, -- uvx ctm-multi-mcp can replace the explicit path in both of the examples above.

Connecting to Codex

Edit ~/.codex/config.toml:

[mcp_servers.ctm-multi-mcp]
command = "/absolute/path/to/ctm-multi-mcp/.venv/bin/ctm-multi-mcp"

[mcp_servers.ctm-multi-mcp.env]
CTM_BASIC_AUTH = "<base64 access_key:secret_key>"
CTM_ACCOUNT_IDS = "12345,67890"

Claude.ai (web)

Not currently supported — claude.ai's connectors require a hosted/remote MCP server (reachable over HTTP), while ctm-multi-mcp runs as a local stdio process. Use Claude Desktop or Claude Code instead until a hosted version exists.

Example Prompts

Once connected, you can drive the server in plain English:

• "Give me a call summary for all accounts for the last 7 days."

• "Show me call dispositions across all accounts — what percentage hang up vs answer?"

• "Break down call volume by source across all accounts for August."

• "Which Google/Bing campaigns drove calls for account 12345 this week, and how many were answered?"

• "Export every answered call over 60 seconds for account 12345 yesterday, with name, city, and state."

• "Which accounts have voice bots configured and what are their names?"

• "List all tracking numbers across all accounts with their routing destination."

• "Show me the call logs for account 12345 and 67890 from yesterday."

• "Which accounts have the most sources configured?"

• "Pull all contacts from every account that have 'test' in the name."

Tool Surface

All tools are read-only and operate across sub-accounts:

Every tool accepts an optional account_ids parameter (comma-separated string) to limit which accounts are queried. Omit to query all discovered accounts.

Working with large result sets

CTM's API caps per_page at roughly 100 records, so a naive integration either misses data past the first page or has to loop pages by hand. This server handles that for you in two ways:

• List tools (list_contacts, list_numbers, list_sources, list_queues, list_users, list_voice_bots, list_voice_menus, list_schedules, list_geo_routes, list_tags, list_texts, and the calls-specific call_disposition_report/call_crosstab/call_export) page through the CTM API automatically up to a max_items (or max_calls) cap — default 500 for most, higher for calls — and flag a WARNING in the output if any account had more records than the cap, so truncation is never silent. Raise the cap rather than paging manually.

• Detail tools (get_call, get_contact, get_number, get_source, get_queue, get_voice_bot, get_voice_menu, get_schedule, get_geo_route, get_user) return the full record by default — which for calls in particular can be 100+ fields including transcripts and touchpoint history — but accept an optional fields parameter (a comma-separated list of top-level keys) to return just what's needed. Cheaper for anything that checks the same few fields across many records.

For call-level analysis specifically, reach for call_disposition_report (aggregate stats), call_crosstab (two-dimension breakdown, e.g. source × status or campaign × status), or call_export (row-level CSV) rather than paging through search_calls — see each tool's docstring for details on why (in short: search_calls filters and totals only reflect a single page, and CTM's calls-list payload already includes fields like name, city, and state, so there's no need to loop get_call afterward to fill those in).

call_crosstab/call_export can also group or filter by real ad-platform attribution — campaign, campaign_id, keyword, ad_group, medium, paid_source — pulled from CTM's per-call "paid" object, not just CTM's own tracking-source label.

Architecture

ctm-multi-mcp
├── server.py          FastMCP server, credential bootstrap
├── config.py          Account filtering config from env/file
├── ctm_client.py      Standalone CTM HTTP client (auth, paginate, paginate_capped, rate-limiting)
├── accounts.py        Sub-account discovery, resolution, status filtering
├── client.py          MultiAccountClient — concurrent operations across accounts
└── tools/
    ├── accounts.py    list_sub_accounts
    ├── calls.py       search_calls, get_call
    ├── contacts.py    list_contacts, get_contact
    ├── geo_routes.py  list_geo_routes, get_geo_route
    ├── numbers.py     list_numbers, get_number
    ├── queues.py      list_queues, get_queue
    ├── reports.py     call_summary_report, call_disposition_report,
    │                  call_crosstab, call_export, reports_series,
    │                  reports_series_dimensions, account_ledger,
    │                  account_summary
    ├── schedules.py   list_schedules, get_schedule
    ├── sources.py     list_sources, get_source
    ├── tags.py        list_tags
    ├── texts.py       list_texts
    ├── users.py       list_users, get_user
    ├── voice_bots.py  list_voice_bots, get_voice_bot
    └── voice_menus.py list_voice_menus, get_voice_menu

Support

email: jason.smith@ctm.com

License

MIT