ringback

ringback

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

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

Highlights

• 📞 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 when the LLM judges 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-alert and ringback-voice:

Platform: macOS, Linux, and Windows (via WSL2 or Docker). TTS is Piper by default (same voice everywhere), falling back to the OS-native voice (say on macOS). The engine is headless — 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.

Server	Tools	What it does
ringback-alert	alert_me, alert_test, alert_status	Fire-and-forget notification: a loud push (ntfy / Pushover) and/or a SIP ring + chat message.
ringback-voice	call_start, converse, get_conversation, call_end, …	A real two-way phone conversation. Rings your phone; you talk, it transcribes you, the LLM replies in speech. Supports barge-in (talk over it and it stops).

The criteria for when to contact you live in the tool descriptions — the calling LLM decides. These servers are just the mechanism.

What a call looks like

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()

The LLM calls call_start once, then converse(...) for each turn. Plain alerts are even simpler: one alert_me(...) call.

---

Let Claude Code install it for you

🤖 Easiest path: copy the prompt below and paste it into Claude 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).

Set up the ringback MCP server for me — it lets you (the agent) call my phone when you
need a decision while I'm away. Repo: https://github.com/mohitbadwal/ringback
(runs on macOS, Linux, or Windows via WSL2/Docker).

Please:
1. Detect my OS and pick the path:
   - macOS                 → ./setup.sh (Homebrew); read docs/SETUP_MACOS.md
   - Linux or Windows-WSL2 → ./setup-linux.sh; read docs/SETUP_LINUX.md
   - Windows without WSL2   → use Docker; read docs/SETUP_DOCKER.md
2. Clone https://github.com/mohitbadwal/ringback, cd in, and read the README + the doc above.
3. Run the setup for my OS (compiles pjsua2 from source — ~20–30 min — installs whisper +
   Piper TTS, downloads models, and creates voice.env).
4. I need a free Linphone SIP account (the phone line): walk me through signing up at
   https://subscribe.linphone.org and installing the Linphone app on my phone, then put my
   SIP id/username/password into voice.env (and set VOICE_DISPLAY_NAME to a caller-ID name).
5. Register it (per OS):
   - macOS:      claude mcp add ringback-voice --scope user -- "$PWD/run_voice_mcp.sh"
   - Linux/WSL2: claude mcp add ringback-voice --scope user -- python3 "$PWD/run_voice_mcp.py"
   - Docker:     see docs/SETUP_DOCKER.md (build image, convert creds to voice.docker.env, then register a `docker run -i` command)
6. macOS only: if a test call fails with error -32000 or a segfault, run ./fix_macos_twolevel.sh.
7. Tell me to start a fresh session, then call me to confirm two-way voice works.

Ask me whenever you need input (SIP credentials, my phone to answer the test call, etc.).