Asterisk Voice MCP Server

A self-hosted Model Context Protocol (MCP) server that lets an AI agent place VoIP phone calls via Asterisk, play TTS messages, capture DTMF input, and optionally record voice responses to be transcribed.

Architecture

graph TD
    Agent[AI Agent (Claude/Hermes)] -->|MCP over stdio| MCPServer[MCP Server (Python)]
    MCPServer -->|ARI HTTP/WebSocket| Asterisk[Asterisk PBX (Docker)]
    Asterisk -->|SIP/RTP| Softphone[Linphone Softphone]
    MCPServer -->|TTS API / STT API| Speechmatics[Speechmatics API]

Features

• Place Calls: Initiate calls to a SIP endpoint.

• TTS: Play dynamically generated speech.

• DTMF Capture: Prompt the user for keypad input.

• Voice Capture & STT: Record user audio and transcribe it via Speechmatics.

• Tool integration: Fully compliant MCP server that exposes tools place_call, send_dtmf, hangup_call, health_check.

Prerequisites

• Docker & Docker Compose

• Python 3.11+

• Linphone app

• Speechmatics API Key (optional, defaults to mock if absent)

Setup

1. Clone the repository (or navigate to directory).

2. Configure environment variables:

   cp .env.example .env
   # Edit .env and provide your SPEECHMATICS_API_KEY if desired.

3. Start Asterisk:

   docker compose up -d

4. Register Linphone:

   • SIP Server: your host IP or domain

   • Port: 5060 (UDP/TCP)

   • Username: linphone-user

   • Password: the value of SIP_PASSWORD from your .env (generated at deploy time; see setup.sh)

Usage

Start the MCP server to expose tools:

python src/mcp_server.py

Example MCP Client Configuration

See config/mcp.json for an example of how to configure an MCP client (like Claude Desktop) to use this server.

Testing without a phone

Run the self-test script, which spins up a mock PJSIP endpoint and runs an end-to-end call test using a local bot.

python scripts/self_test.py

Security Notes

• Never expose ARI/SIP to the public internet without proper authentication, firewalls, and Fail2Ban.

• Secrets should remain in .env.

• Use strong endpoint secrets for SIP registrations.

• Lock down RTP ports.

License

MIT License