aircall-mcp

A local, read-only Model Context Protocol server for the official Aircall REST API.

[!IMPORTANT] This is an independent open-source project. It is not built, maintained, or endorsed by Aircall.

Why this server

Aircall provides an official REST API but does not provide a client-facing MCP server for reading calls and transcripts. aircall-mcp provides that MCP layer while keeping credentials and Aircall data on the local machine:

• Read-only by construction: only documented GET endpoints are implemented.
• Local stdio transport: no web server, hosted proxy, account, or subscription.
• Fixed API origin: credentials are sent only to https://api.aircall.io.
• No persistence: responses, transcripts, and contacts are not written to disk.
• Bounded output: pagination, compact call results, and transcript slicing limit context usage.
• Sensitive media URLs omitted by default: recording, voicemail, asset, and number-message URLs require explicit opt-in.

Tools

All 21 tools are annotated as read-only, non-destructive, and idempotent.

Tool	Aircall endpoint
aircall_ping	GET /v1/ping
aircall_get_company	GET /v1/company
aircall_list_users	GET /v2/users
aircall_get_user	GET /v2/users/{id-or-email}
aircall_list_calls	GET /v1/calls
aircall_get_call	GET /v1/calls/{id}
aircall_search_calls	GET /v1/calls/search
aircall_get_transcription	GET /v1/calls/{id}/transcription
aircall_get_sentiments	GET /v1/calls/{id}/sentiments
aircall_get_topics	GET /v1/calls/{id}/topics
aircall_get_summary	GET /v1/calls/{id}/summary
aircall_get_action_items	GET /v1/calls/{id}/action_items
aircall_list_numbers	GET /v1/numbers
aircall_get_number	GET /v1/numbers/{id}
aircall_list_contacts	GET /v1/contacts
aircall_get_contact	GET /v1/contacts/{id}
aircall_search_contacts	GET /v1/contacts/search
aircall_list_teams	GET /v1/teams
aircall_get_team	GET /v1/teams/{id}
aircall_list_tags	GET /v1/tags
aircall_get_tag	GET /v1/tags/{id}

Conversation Intelligence tools require the applicable Aircall AI feature and data to be available for that call.

Install

Requirements: Node.js 20 or newer and an Aircall API key pair.

git clone https://github.com/growth-box/aircall-mcp.git
cd aircall-mcp
npm install
npm run build

Create API credentials in Aircall Dashboard → Integrations → API keys. Aircall shows the API token only once.

Configure an MCP client

The server reads credentials from its process environment:

{
  "mcpServers": {
    "aircall": {
      "command": "node",
      "args": ["/absolute/path/to/aircall-mcp/dist/index.js"],
      "env": {
        "AIRCALL_API_ID": "your-api-id",
        "AIRCALL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Do not commit or share a configuration containing real credentials.

Pi with macOS Keychain

Pi's MCP adapter can resolve environment values from commands when the value starts with !. This keeps secrets out of JSON configuration.

Store the credentials interactively:

./scripts/macos-keychain-setup.sh

Then add this server to ~/.config/mcp/mcp.json:

{
  "mcpServers": {
    "aircall": {
      "command": "node",
      "args": ["/absolute/path/to/aircall-mcp/dist/index.js"],
      "env": {
        "AIRCALL_API_ID": "!security find-generic-password -s aircall-mcp -a AIRCALL_API_ID -w",
        "AIRCALL_API_TOKEN": "!security find-generic-password -s aircall-mcp -a AIRCALL_API_TOKEN -w"
      },
      "lifecycle": "lazy"
    }
  }
}

Reload Pi, then connect or call aircall_ping.

Aircall API constraints

At the time of implementation, Aircall documents:

• 120 API requests per minute per company.
• A maximum page size of 50.
• A maximum of 10,000 paginated calls or contacts; use date windows to go beyond that.
• Six months of call history through the Public API.

The client retries one 429 response using Aircall's retry/reset headers. It otherwise leaves request scheduling to the MCP client.

Data handling

Call records, contacts, phone numbers, and transcripts may contain personal or confidential information. This server does not store them, but its results are sent to the connected MCP client and ultimately to that client's language-model provider. Review that provider's privacy and retention controls.

Media URLs are omitted by default because they can grant access to recordings or voicemail. Pass the relevant explicit include_*_urls option only when needed. On call-list and call-search tools, opting into media URLs returns full call records even when compact is left at its default.

Set AIRCALL_TIMEOUT_MS to a positive integer to override the default 30-second request timeout.

See SECURITY.md for the full security model.

Development

npm test
npm run typecheck

Tests use mocked Aircall responses and never require live credentials.

License

MIT