sip-phone-mcp

# SIP Phone MCP An MCP server that gives AI agents the ability to make outbound phone calls. ## Install Choose one of three ways: ### Option 1: Claude Code plugin (recommended) ```bash claude plugin marketplace add darwincr/sip-phone-mcp claude plugin install sip-phone-mcp@darwincr-sip-phone-mcp ``` Updates are automatic. Requires Claude Code v2.1+. ### Option 2: Zero-clone with uvx Add this directly to any MCP client config. No git clone needed -- `uvx` fetches and runs the package from GitHub automatically: ```json { "mcpServers": { "sip-phone": { "command": "uvx", "args": [ "--refresh", "--from", "git+https://github.com/darwincr/sip-phone-mcp.git", "sip-phone-mcp" ] } } } ``` > Remove `--refresh` if you prefer faster startup over auto-updates. ### Option 3: Local install ```bash git clone https://github.com/darwincr/sip-phone-mcp.git && cd sip-phone-mcp uv tool install -e . ``` Then point your MCP client at the installed binary: ```json { "mcpServers": { "sip-phone": { "command": "sip-phone-mcp" } } } ``` ## Setup ```bash # 1. Copy an example env file and fill in your values cp .env.example .env # choose from: .env.example, .env.openai, .env.budget, .env.google, .env.low-latency # 2. Start the Docker infrastructure docker compose up --force-recreate -d ``` Example configs are also included for VS Code (`.vscode/mcp.json`) and OpenCode (`opencode.json`). ### Preset Env Files | File | Providers | API Keys Needed | |------|-----------|-----------------| | `.env.example` | Deepgram + OpenAI + Cartesia (best quality) | OPENAI, DEEPGRAM, CARTESIA | | `.env.low-latency` | Deepgram + OpenAI + Cartesia (optimized) | OPENAI, DEEPGRAM, CARTESIA | | `.env.openai` | All OpenAI | OPENAI | | `.env.google` | All Google | GOOGLE | | `.env.budget` | Deepgram + OpenAI (cost-effective) | OPENAI, DEEPGRAM | ## What You Need - **Python 3.11+** and [uv](https://docs.astral.sh/uv/) - **Docker Desktop** - **A SIP trunk provider** -- any provider with SIP credentials or sip extension - **API keys** for your chosen AI providers (see preset table above) - **Port forwarding** is typically not required (outbound calls only). If you experience one-way audio or failed calls, forward these on your router: - UDP 5060 (SIP signaling) - UDP 30000-30100 (RTP media) ## What the AI Can Do | Tool | What it does | |------|-------------| | `make_call` | Call a phone number, wait for it to finish, return the transcript and summary | | `dispatch_voice_agent` | Start a call without waiting (for parallel calls) | | `get_call_status` | Check if an async call is still running | | `get_call_transcript` | Get the transcript of a finished call | | `list_recent_calls` | See recent calls and their status | | `hangup_call` | Hang up an active call | | `get_system_status` | Health check for LiveKit connectivity and agent status | | `get_logs` | View recent logs for debugging | ### Example > "Call +15551234567 and confirm their dental appointment for next Tuesday at 3pm." The AI uses `make_call` with instructions for the voice agent, waits for the call to finish, and gets back the full transcript and a summary. ## How It Works ``` AI Client ──MCP──► sip-phone-mcp ──LiveKit API──► LiveKit + SIP ──► Phone Network (MCP server + (Docker) voice agent) ``` Everything runs as a single process. When the MCP server starts, it automatically provisions the SIP trunk, runs smoke tests against your AI providers, and launches the voice agent worker. The Docker stack handles the actual telephony (SIP signaling, media routing). On each call, the voice agent connects to a LiveKit room, dials out via SIP, and runs a voice conversation loop: STT -> LLM -> TTS. When the call ends, the transcript and an LLM-generated summary are saved. ## Logs ``` ~/.sip-phone-mcp/sip-phone-mcp.log ``` Override the location with the `SIP_LOG_DIR` env var.