Ringback

Your AI agent can call your phone — and actually talk to you.

ringbackgives an LLM (Claude, or any MCP client) tools toreach you on your phone— from a one-way "fierce" alert all the way to alive, interruptible voice conversation— using only free, self-hosted pieces. No paid telephony. No extra API key for the conversation: the model already driving the MCPisthe voice on the line.

- 📞Two-way voice calls— the agent rings your phone, you talk, it transcribes you and replies in speech.Barge-in: talk over it and it stops.
- 🔔Tiered alerts— a loud push (ntfy / Pushover) or a real SIP ring + chat message, fired only whenthe LLMjudges it urgent.
- 🆓Free & self-hosted— pjsua2 + whisper.cpp + Piper neural TTS + a free Linphone SIP account. No Twilio, no per-minute fees.
- 🧠No conversation API key— the calling model is the brain; these tools are just its ears and mouth.

It ships two MCP servers,ringback-alertandringback-voice:

Platform:macOS,Linux, andWindows(via WSL2 or Docker). TTS isPiperby default (same voice everywhere), falling back to the OS-native voice (sayon macOS). The engine isheadless— it never opens a local mic/speaker (all audio is WAV ↔ SIP/RTP), so no sound card is required. Setup guides:macOS·Linux·Windows·Docker.

agent → call_start("Your nightly deploy failed — want me to walk you through it?") 📞 your phone rings; you pick up and hear the line you → "yeah, which step broke?" agent → "The database migration. I can roll it back and retry — want that?" you → "yes, do it" ← you can also just talk over the agent to interrupt agent → call_end()

If you haveDockerand a freeLinphoneaccount, this is the fastest path — no local build:

/plugin marketplace add mohitbadwal/ringback /plugin install ringback@ringback

Claude Code prompts for your SIP details (and optional alert backends), stores secrets in your OS keychain, and registers bothringback-voiceandringback-alertplus the watchdog skill. The engine runs in the prebuilt image (pulled on first call). Seeplugin/README.md.

🤖 Easiest path:copy the prompt below and paste it intoClaude Code— it'll clone, build, configure, and register everything, asking you only for what it needs (a free SIP account + your phone to answer a test call).

Full walkthrough + env-var reference:Set up ringback-voicebelow.

- Cross-platform.macOS (native), Linux (native), Windows (via WSL2 or Docker). The engine is headless — no sound card needed. Native Windows (MSVC) is intentionally not supported; WSL2/Docker is the Windows path.
- Not ChatGPT-realtime.The voice loop is record → whisper STT → LLM → Piper/say TTS, so expect~1–2 s per turn. It's a reliable walkie-talkie with barge-in, not a streaming realtime voice.
- The voice feature depends on GPL software(pjproject/pjsua2). This repo is Apache-2.0, but redistributing a bundle that links pjsua2 carries GPL obligations — seeNOTICE. The ringback-alert server is unaffected.
- Your machine must be awake and online, and for a voice call a Claude session must be live (it's the brain) for the duration.
- Barge-in assumes low acoustic echo(handset or headset). On speakerphone, the TTS can echo into the mic and false-trigger "interruption." There's no echo cancellation in this path.
- iOS push reality:a self-hosted/free push can't truly pierce Focus/Silent on iPhone except via Pushover's Critical Alerts (paid) — see ringback-alert notes below.

LLM (Claude) ──MCP tools──▶ ringback-voice server (Python) │ call_start / converse / listen / speak ▼ pjsua2 (SIP+SRTP, built from source) ──▶ Linphone SIP server │ Piper/say → ffmpeg → WAV (speak) │ APNs VoIP push │ record → whisper.cpp (listen) ▼ └───────────────────────────────────▶ your iPhone rings

- macOS(Apple Silicon or Intel) withHomebrew— run./setup.sh
- Linux(Debian/Ubuntu/Fedora) — run./setup-linux.sh(seedocs/SETUP_LINUX.md)
- Windows— WSL2 (run./setup-linux.shinside it) or Docker Desktop (seedocs/SETUP_WINDOWS.md)
- Any OS with Docker—docker build -t ringback .(seedocs/SETUP_DOCKER.md)

git clone https://github.com/mohitbadwal/ringback && cd ringback ./setup.sh

On Linux?Use./setup-linux.shinstead — it does the same build with apt/dnf and needsnoOpenSSL relink.On Windows?Use WSL2 (docs/SETUP_WINDOWS.md) orDocker. Register the server with the cross-platform launcherpython3 run_voice_mcp.py(the.shis macOS-only).

Hit a snag on macOS?[docs/SETUP_MACOS.mdis a field-tested root-cause + troubleshooting guide (build target, the OpenSSL flat-namespace fix, whisper model, symptom→fix table).

2. Get a free SIP account(this is the phone that rings):

3. Fill invoice.env(already created by setup.sh — just edit it). Onlythreevars are required:

export VOICE_SIP_ID="sip:yourname@sip.linphone.org" export VOICE_SIP_USER="yourname" export VOICE_SIP_PASS="your-password"

# macOS: claude mcp add ringback-voice --scope user -- "$PWD/run_voice_mcp.sh" # Linux / Windows-WSL2 (cross-platform launcher): claude mcp add ringback-voice --scope user -- python3 "$PWD/run_voice_mcp.py" # Any OS via Docker (convert creds to voice.docker.env first — see docs/SETUP_DOCKER.md): claude mcp add ringback-voice --scope user -- docker run -i --rm --network host --env-file voice.docker.env ringback

Then in afreshClaude session say:"Use ringback-voice to call me and say hello."Your phone should ring.

Claude Desktopinstead of Code? Add this to~/Library/Application Support/Claude/claude_desktop_config.json(absolute path required; restart the app):

{ "mcpServers": { "ringback-voice": { "command": "/absolute/path/to/ringback/run_voice_mcp.sh" } } }

ringback-alert reads its config from theMCP client'senvblock(no file to source). Register it with the channels you want:

…