Ringback

Permite que los agentes de IA inicien llamadas de voz bidireccionales y envíen alertas escalonadas a tu teléfono utilizando soluciones de telefonía gratuitas y autoalojadas.

GitHub

Prueba este MCPPatrocinado

Documentación

ringback

Tu agente de IA puede llamar a tu teléfono — y realmente hablar contigo.

ringback le da a un LLM (Claude, o cualquier cliente MCP) herramientas para contactarte en tu teléfono — desde una alerta unidireccional "intensa" hasta una conversación de voz en vivo e interrumpible — usando solo piezas gratuitas y autoalojadas. Sin telefonía de pago. Sin clave API adicional para la conversación: el modelo que ya impulsa el MCP es la voz en la línea.

Aspectos destacados

📞 Llamadas de voz bidireccionales — el agente llama a tu teléfono, tú hablas, te transcribe y responde en voz. Interrupción: habla por encima y se detiene.
🔔 Alertas escalonadas — una notificación push fuerte (ntfy / Pushover) o un timbre SIP real + mensaje de chat, activada solo cuando el LLM lo juzga urgente.
🆓 Gratuito y autoalojado — pjsua2 + whisper.cpp + Piper TTS neuronal + una cuenta SIP gratuita de Linphone. Sin Twilio, sin tarifas por minuto.
🧠 Sin clave API de conversación — el modelo que llama es el cerebro; estas herramientas son solo sus oídos y su boca.

Incluye dos servidores MCP, ringback-alert y ringback-voice:

Plataforma: macOS, Linux y Windows (mediante WSL2 o Docker). El TTS es Piper por defecto (misma voz en todas partes), con respaldo a la voz nativa del sistema operativo (say en macOS). El motor es headless — nunca abre un micrófono/altavoz local (todo el audio es WAV ↔ SIP/RTP), por lo que no se requiere tarjeta de sonido. Guías de configuración: macOS · Linux · Windows · Docker.

Servidor	Herramientas	Qué hace
ringback-alert	`alert_me`, `alert_test`, `alert_status`	Notificación de disparo y olvido: un push fuerte (ntfy / Pushover) y/o un timbre SIP + mensaje de chat.
ringback-voice	`call_start`, `converse`, `get_conversation`, `call_end`, …	Una conversación telefónica bidireccional real. Llama a tu teléfono; tú hablas, te transcribe, el LLM responde en voz. Admite interrupción (habla por encima y se detiene).

Los criterios sobre cuándo contactarte viven en las descripciones de las herramientas — el LLM que llama decide. Estos servidores son solo el mecanismo.

Cómo es una llamada

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

El LLM llama a call_start una vez, luego converse(...) para cada turno. Las alertas simples son aún más fáciles: una sola llamada a alert_me(...).

Instalar como plugin de Claude Code (Docker — un comando)

Si tienes Docker y una cuenta gratuita de Linphone, este es el camino más rápido — sin compilación local:

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

Claude Code te pide tus datos SIP (y backends de alerta opcionales), guarda los secretos en el llavero de tu sistema operativo y registra tanto ringback-voice como ringback-alert además de la habilidad watchdog. El motor se ejecuta en la imagen precompilada (descargada en la primera llamada). Consulta plugin/README.md.

¿Prefieres sin Docker, o quieres la compilación nativa? Usa el prompt de pegado a continuación o los pasos manuales.

Deja que Claude Code lo instale por ti

🤖 Camino más fácil: copia el prompt a continuación y pégalo en Claude Code — clonará, compilará, configurará y registrará todo, pidiéndote solo lo que necesita (una cuenta SIP gratuita + tu teléfono para responder una llamada de prueba).

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

¿Prefieres hacerlo a mano? El inicio rápido y el recorrido completo están a continuación.

Inicio rápido

git clone https://github.com/mohitbadwal/ringback && cd ringback
./setup.sh        # installs EVERYTHING (toolchain, pjsua2, whisper model, deps) + creates voice.env
# edit voice.env → add your 3 SIP vars (free account: https://subscribe.linphone.org), then:
claude mcp add ringback-voice --scope user -- "$PWD/run_voice_mcp.sh"

Recorrido completo + referencia de variables de entorno: Configurar ringback-voice a continuación.

Advertencias honestas (léelas primero)

Multiplataforma. macOS (nativo), Linux (nativo), Windows (mediante WSL2 o Docker). El motor es headless — no se necesita tarjeta de sonido. Windows nativo (MSVC) no se admite intencionalmente; WSL2/Docker es el camino para Windows.
No es ChatGPT-realtime. El bucle de voz es grabar → whisper STT → LLM → Piper/say TTS, así que espera ~1–2 s por turno. Es un walkie-talkie confiable con interrupción, no una voz en tiempo real con streaming.
La función de voz depende de software GPL (pjproject/pjsua2). Este repositorio es Apache-2.0, pero redistribuir un paquete que enlaza pjsua2 conlleva obligaciones GPL — consulta NOTICE. El servidor ringback-alert no se ve afectado.
Tu máquina debe estar encendida y en línea, y para una llamada de voz debe haber una sesión de Claude activa (es el cerebro) durante toda la duración.
La interrupción asume bajo eco acústico (auricular o audífonos). En altavoz, el TTS puede hacer eco en el micrófono y activar falsamente la "interrupción". No hay cancelación de eco en este camino.
Realidad del push en iOS: un push autoalojado/gratuito no puede realmente atravesar Focus/Silent en iPhone excepto mediante Critical Alerts de Pushover (de pago) — consulta las notas de ringback-alert a continuación.

Arquitectura

  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

ringback-alert es más simple: ejecuta ntfy/Pushover HTTP y/o baresip para un timbre SIP + mensaje de chat.

Requisitos previos

Uno de:
- macOS (Apple Silicon o Intel) con Homebrew — ejecuta ./setup.sh
- Linux (Debian/Ubuntu/Fedora) — ejecuta ./setup-linux.sh (consulta docs/SETUP_LINUX.md)
- Windows — WSL2 (ejecuta ./setup-linux.sh dentro) o Docker Desktop (consulta docs/SETUP_WINDOWS.md)
- Cualquier sistema operativo con Docker — docker build -t ringback . (consulta docs/SETUP_DOCKER.md)
Una cuenta SIP gratuita de Linphone (sip.linphone.org) y la aplicación Linphone para iOS/Android (para las funciones de timbre/voz)
Python 3.10+ (los enlaces pjsua2 se compilan contra el python3 al que apuntes)

Configurar ringback-voice — 4 pasos

1. Clona + instala todo:

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

setup.sh instala el toolchain, compila pjsua2 desde el código fuente (~20–30 min — no existe fórmula Homebrew para los enlaces), reenlaza las dylibs de pjproject a un espacio de nombres OpenSSL de dos niveles (la corrección de macOS que hace funcionar SIP/SRTP), descarga el modelo whisper, instala Piper + una voz, instala dependencias y crea voice.env por ti. Seguro de re-ejecutar. (Anula PYTHON_BIN / PJPROJECT_DIR / WHISPER_MODEL_NAME si tu estructura difiere.)

¿En Linux? Usa ./setup-linux.sh en su lugar — hace la misma compilación con apt/dnf y no necesita reenlace de OpenSSL. ¿En Windows? Usa WSL2 (docs/SETUP_WINDOWS.md) o Docker. Registra el servidor con el lanzador multiplataforma python3 run_voice_mcp.py (el .sh es solo para macOS).

¿Problemas en macOS? docs/SETUP_MACOS.md es una guía de causa raíz + solución de problemas probada en campo (objetivo de compilación, la corrección de espacio de nombres plano de OpenSSL, modelo whisper, tabla síntoma→solución).

2. Obtén una cuenta SIP gratuita (este es el teléfono que suena):

Regístrate en https://subscribe.linphone.org (o toca Crear cuenta en la aplicación Linphone). Obtienes un nombre de usuario y contraseña; tu dirección es sip:<username>@sip.linphone.org.
Instala la aplicación Linphone en tu iPhone, inicia sesión y confirma que muestra Conectado.

3. Completa voice.env (ya creado por setup.sh — solo edítalo). Solo tres variables son obligatorias:

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

Referencia completa de variables:

Variable	Obligatoria	Predeterminada	Qué es
`VOICE_SIP_ID`	✅	—	Tu dirección SIP, p. ej. `sip:you@sip.linphone.org`
`VOICE_SIP_USER`	✅	—	Nombre de usuario SIP (la parte antes de `@`)
`VOICE_SIP_PASS`	✅	—	Tu contraseña SIP
`VOICE_SIP_CALLEE`	—	= `VOICE_SIP_ID`	Dirección a llamar (normalmente tú mismo)
`VOICE_SIP_PROXY`	—	`sip:sip.linphone.org;transport=tls`	Registrador/proxy SIP
`WHISPER_MODEL`	—	`~/.whisper-models/ggml-small.en.bin`	Modelo STT: `base.en` (rápido) · `small.en` (predeterminado) · `medium.en` (preciso)
`VOICE_TTS`	—	`auto`	Motor TTS: `auto` (Piper si está instalado, si no voz del SO) · `piper` · `say` · `espeak` · `sapi`
`VOICE_PIPER_MODEL`	—	`~/.piper-voices/en_US-lessac-medium.onnx`	Voz de Piper (`.onnx`; necesita el `.onnx.json` correspondiente junto a ella)
`VOICE_TTS_CMD`	—	—	Plantilla de comando TTS personalizada con `{text}`/`{out}` (anula `VOICE_TTS`)
`VOICE_NULL_AUDIO`	—	`auto`	Forzar dispositivo de audio nulo de pjsua2 (`auto` = activado excepto macOS; `1`/`0` para forzar)
`RINGBACK_PRESENCE`	—	—	Anular inactividad/presencia del watchdog: `present` o `absent` (para Wayland/headless)
`PJPROJECT_DIR`	—	`~/build/pjproject-2.17`	Directorio de compilación de pjsua2 (auto-detectado)
`PYTHON_BIN`	—	`$(command -v python3)`	Python que tiene pjsua2 (auto-detectado)
`OPENSSL_PREFIX`	—	`$(brew --prefix openssl@3)`	Bibliotecas OpenSSL (macOS; auto-detectadas)

4. Registra + prueba:

# 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

Luego en una sesión nueva de Claude di: "Usa ringback-voice para llamarme y saludarme." Tu teléfono debería sonar.

¿Claude Desktop en lugar de Code? Agrega esto a ~/Library/Application Support/Claude/claude_desktop_config.json (se requiere ruta absoluta; reinicia la aplicación):
{ "mcpServers": { "ringback-voice": { "command": "/absolute/path/to/ringback/run_voice_mcp.sh" } } }

Configurar ringback-alert (opcional)

ringback-alert lee su configuración del bloque env del cliente MCP (sin archivo que cargar). Regístralo con los canales que quieras:

# Claude Code
claude mcp add ringback-alert --scope user \
  --env ALERT_CHANNEL=ntfy \
  --env NTFY_URL=https://ntfy.sh/your-long-random-topic \
  -- /opt/homebrew/bin/uv --directory "$PWD" run server.py

Consulta alert.env.example para todas las variables (ntfy / Pushover / timbre SIP). Usa un tema ntfy largo y aleatorio — cualquiera que lo conozca puede leer/publicar.

Usar ringback-voice (la conversación)

El LLM impulsa un bucle simple:

reply = call_start("Hi, it's your assistant — your deploy failed. Want details?")
# rings the phone, speaks the line, returns the user's first words
reply = converse("It failed on the database migration step. Want me to retry it?")
# speaks AND listens in one interruptible turn
... repeat converse() each turn ...
call_end()   # when the user says "bye" / hangs up

converse(text) habla mientras escucha. Si hablas por encima, se detiene inmediatamente y le dice al LLM hasta dónde llegó y qué dijiste (interrupción).
get_conversation() devuelve la transcripción completa hasta ahora — ambos lados, más dónde se interrumpió.
El TTS lee el texto literalmente, por lo que las descripciones de herramientas instruyen al modelo a hablar resúmenes en lenguaje sencillo, nunca registros/códigos crudos — esos van por alert_me como texto en su lugar.

Compensación precisión/velocidad del modelo Whisper (configura WHISPER_MODEL): base.en (rápido/aproximado) → small.en (equilibrado, predeterminado) → medium.en (más preciso/lento).

Usar ringback-alert (notificaciones)

alert_me(message, severity, title) con severity = info | warn | critical. Canales mediante ALERT_CHANNEL (lista separada por comas de ntfy, pushover, call):

ntfy — push gratuito; fuerte pero no atraviesa iOS Focus/Silent a menos que esté en la lista blanca por Focus.
Pushover — $5 único; verdaderas Critical Alerts de iOS (atraviesan Focus/Silent, se repiten hasta confirmar) en critical.
call — timbre SIP gratuito + mensaje de chat de Linphone mediante baresip; suena a pantalla completa, solo en critical por defecto.

Un guardia de límite de velocidad integrado (predeterminado 5/60s, por proceso) evita que un llamador defectuoso te spammee.

Habilidad incluida: watchdog

skills/watchdog/ es una habilidad de Claude lista para usar construida sobre estos servidores. Observa una condición que le des (una ejecución de CI, un despliegue, un pod, un archivo) y escala solo cuando realmente estás lejos del portátil — estado de chat → advertencia de chat → push ringback-alert → llamada ringback-voice — juzgado por tiempo de inactividad de entrada (macOS, Linux o Windows; consulta platform_compat.hid_idle_seconds). Nunca te interrumpe mientras escribes, y desescala en el momento en que tocas el teclado.

cp -r skills/watchdog ~/.claude/skills/watchdog   # install for Claude Code

Luego: /watchdog <what to watch> | priority=<low|medium|critical> — low = solo chat, medium = puede enviar una alerta telefónica, critical = puede hacer una llamada. Diseño completo en skills/watchdog/SKILL.md.

Seguridad

Las credenciales SIP viven únicamente en tu archivo local voice.env (ignorado por git) (y en el archivo accounts de baresip para la alerta de ringback) — nunca en el repositorio ni en la configuración del cliente MCP cuando puedas evitarlo.
El servidor de voz solo llama al URI SIP único que configures — no puede marcar números arbitrarios.
Trata los temas de ntfy como secretos (usa un tema aleatorio largo); no pongas detalles sensibles en los cuerpos de las alertas en ntfy.sh público.
Consulta NOTICE para la advertencia de licencia GPL/pjproject antes de redistribuir.

Licencia

Apache-2.0 (ver LICENSE), con una advertencia importante de GPL para la dependencia pjproject del componente de voz — ver NOTICE.

Créditos

Construido sobre pjproject/pjsua2, whisper.cpp, baresip, ntfy y Linphone.