SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentscallhub-mcp

callhub-mcp

Python-based MCP tool providing a comprehensive set of functions for managing contacts, phonebooks, agents, teams, campaigns, and other CallHub resources.

Open website

About this tool

CallHub MCP Server is an MCP (Model Context Protocol) server that exposes CallHub's REST API as tools, enabling any MCP-compatible AI assistant to manage CallHub resources through natural language. CallHub itself is a calling and texting platform for advocacy organizations, unions, political organizations, nonprofits, and organizing teams, offering features such as voice broadcasting, call centers/phone banking, P2P and bulk texting, and contact management. This server primarily wraps public endpoints, and also includes some internal/extension endpoints (each tool is marked in the reference documentation).

Main capabilities The server registers approximately 135 tools, covering various CallHub resource areas:

  • Contacts: create, get, update, delete, as well as listContacts, searchContacts, bulkCreateContacts, addContactNotes, custom fields, and tags.
  • Contact lists (also known as phonebooks): create, get, update, delete, list, add/remove contacts, count.
  • Agents and teams: create, get, list agents, live agents, team CRUD and member management, activation URL export.
  • Campaigns: creation, retrieval, listing, status updates, copying, deletion, and agent assignment for call centers, voice broadcasts, text broadcasts, P2P, and relational organizing campaigns.
  • DNC and suppression: DNC lists and contacts, addToDnc / removeFromDnc, addToSuppressionList.
  • Numbers: rent, auto-rent texting numbers, list rented/verified numbers, re-verify.
  • Media, Webhooks, Reports: media list/upload, Webhook CRUD, campaign statistics, credit usage, export job polling, short link statistics, shareCredits. Tool names follow CallHub's product vocabulary (such as createContactList, createVoiceBroadcastCampaign, createTextBroadcast, addTagsToContact). Legacy names (such as createPhonebook, createVbCampaign, createSmsBroadcast, etc.) remain available as hidden aliases, so saved workflows can continueto run; new work should use the canonical names.

Usage This server runs locally via stdio and authenticates to CallHub using an API key. It works with any MCP client, including Claude Desktop, Cursor, Windsurf, Cline, Continue, OpenAI Codex, Gemini CLI, and others, and is provided as a one-click .mcpb package for Claude Desktop.

Installation (Claude Desktop): Download the package for your platform from dist/ or the latest release: macOS (Apple Silicon): callhub-macos-arm64.mcpb; macOS (Intel): callhub-macos-x64.mcpb; Windows (x64): callhub-win-x64.mcpb; Linux (x64): callhub-linux-x64.mcpb. Open Claude Desktop → Settings → Extensions, drag the file in (or double-click it). Enter the extension settings (see Configuration). Enable the extension. The CallHub tools are then available. Requirements: Python 3.10–3.14 available on the system. Each package bundles dependencies for every Python version in that range, so any version will work.

Installation (other MCP clients): Any MCP client that can launch a local command can run this server. Clone and install dependencies, then point the client at src/server.py. Then register the server with the client. Most clients use an mcpServers JSON block—pass credentials via environment variables. Client-specific quick commands:

  • Gemini CLI: gemini mcp add callhub python3 /absolute/path/to/callhub-mcp/src/server.py (then set the CALLHUB_* environment variables).
  • OpenAI Codex: add an [mcp_servers.callhub] block in ~/.codex/config.toml, command = "python3", args = ["/absolute/path/.../src/server.py"].
  • Cursor / Windsurf / Cline / Continue: add the above mcpServers block to the client's MCP configuration file. If the server's dependencies are not on the system Python, use the venv's Python (.venv/bin/python3) as the command.

Configuration: Two values are needed, both from Settings → Account → API Keys in the CallHub dashboard:

  • API Key——the key shown there.
  • API Domain——the base URL shown there, which varies by region (e.g., https://api-na1.callhub.io）。 In Claude Desktop, these are extension settings. For other clients, set them as the CALLHUB_API_KEY and CALLHUB_BASE_URL environment variables. Media upload (optional): the tool is disabled unless uploadMediaFile points to an approved folder (the media upload directory setting or the CALLHUB_MEDIA_DIR environment variable). The tool can then only read files from within that folder (in addition to a media extension check), so it can never read arbitrary files on the host.

Multiple accounts: The configured key is the default account. To use more accounts, have the assistant configure one by name (the configureAccount tool), then reference it by name in requests—for example, "list the teams in my personal account." Requests that do not specify an account use default. Credentials for other accounts are stored in a local .env file, using the pattern CALLHUB_<ACCOUNT>_API_KEY / _BASE_URL / _USERNAME.

When to use it Suitable for scenarios that require managing CallHub resources in natural language through an AI assistant, such as bulk creating contacts, managing campaigns, assigning agents, handling DNC lists, renting numbers, uploading media, configuring webhooks, and retrieving reports. Especially suitable for users such as advocacy organizations, unions, political organizations, nonprofit institutions, and organizational teams that use CallHub for calling and texting work.

Limitations and notes

  • The CallHub API has rate limits; the server exposes 429 responses instead of masking them. In particular, searchContacts is limited to about one request per second—prefer a single searchContacts call over rapidly paging through listContacts. For bulk work, use the bulk endpoint (bulkCreateContacts) instead of many single calls.
  • Newly created agents are in a pending state and must verify their email before they appear in listAgents. Manage them through an activation export workflow: exportAgentActivationUrls (or getAgentActivationExportUrl) to obtain the export; download the activation CSV from the CallHub UI; processAgentActivationCsv (or processUploadedActivationCsv) reads it. Earlier versions bundled a Selenium/Chrome flow to automatically set agent passwords, but it was removed to keep the server lightweight and reliable—distribute the activation URLs to agents, or activate them in the CallHub UI.
  • The build generates a callhub.mcpb for the platform being built (some dependencies ship compiled wheels, so the package is OS/architecture-specific). build-all.sh cross-downloads platform wheels (without executing them) and packages one package per platform, with each package containing compiled dependencies for all supported Python versions. Build requirements: python3 (3.10+) and the mcpb CLI (invoked via npx @anthropic-ai/mcpb, so Node.js is required at build time).
  • Repository structure: manifest.json——MCPB extension manifest (server entry point, user_config); src/server.py——registers every tool and starts the MCP server (stdio); src/callhub/——API client, authentication, and one module per resource; docs/API_REFERENCE.md——tool-to-endpoint reference; build.sh——reproducible package build.
  • The API key is provided through extension settings (Claude Desktop) or environment variables and is not committed to this repository. Using an API key with the least privilege scope is recommended.

Related tools

Browse category