aircall-mcp

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

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.

Related MCP server: slack-readonly-mcp

Tools

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

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