Ringback

Permite que agentes de IA iniciem chamadas de voz bidirecionais e enviem alertas em níveis para o seu telefone usando soluções de telefonia gratuitas e auto-hospedadas.

GitHub

Experimente este MCPPatrocinado

Documentação

ringback

Seu agente de IA pode ligar para o seu telefone — e realmente conversar com você.

O ringback dá a um LLM (Claude, ou qualquer cliente MCP) ferramentas para alcançar você no seu telefone — desde um alerta "agressivo" de mão única até uma conversa de voz ao vivo e interrompível — usando apenas componentes gratuitos e auto-hospedados. Sem telefonia paga. Sem chave de API extra para a conversa: o modelo que já dirige o MCP é a voz na linha.

Destaques

📞 Chamadas de voz bidirecionais — o agente liga para o seu telefone, você fala, ele transcreve você e responde em fala. Barge-in: fale por cima e ele para.
🔔 Alertas em níveis — um push alto (ntfy / Pushover) ou um toque SIP real + mensagem de chat, disparado apenas quando o LLM julga urgente.
🆓 Gratuito e auto-hospedado — pjsua2 + whisper.cpp + Piper TTS neural + uma conta SIP Linphone gratuita. Sem Twilio, sem taxas por minuto.
🧠 Sem chave de API de conversa — o modelo que chama é o cérebro; essas ferramentas são apenas seus ouvidos e boca.

Ele entrega dois servidores MCP, ringback-alert e ringback-voice:

Plataforma: macOS, Linux e Windows (via WSL2 ou Docker). O TTS é Piper por padrão (mesma voz em todos os lugares), com fallback para a voz nativa do SO (say no macOS). O mecanismo é headless — ele nunca abre um microfone/alto-falante local (todo o áudio é WAV ↔ SIP/RTP), então nenhuma placa de som é necessária. Guias de configuração: macOS · Linux · Windows · Docker.

Servidor	Ferramentas	O que faz
ringback-alert	`alert_me`, `alert_test`, `alert_status`	Notificação fire-and-forget: um push alto (ntfy / Pushover) e/ou um toque SIP + mensagem de chat.
ringback-voice	`call_start`, `converse`, `get_conversation`, `call_end`, …	Uma conversa telefônica bidirecional real. Liga para o seu telefone; você fala, ele transcreve você, o LLM responde em fala. Suporta barge-in (fale por cima e ele para).

Os critérios para quando entrar em contato com você vivem nas descrições das ferramentas — o LLM que chama decide. Esses servidores são apenas o mecanismo.

Como é uma chamada

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

O LLM chama call_start uma vez, depois converse(...) para cada turno. Alertas simples são ainda mais fáceis: uma única chamada alert_me(...).

Instalar como plugin do Claude Code (Docker — um comando)

Se você tem Docker e uma conta Linphone gratuita, este é o caminho mais rápido — sem build local:

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

O Claude Code pede seus dados SIP (e backends de alerta opcionais), armazena segredos no chaveiro do seu SO e registra ambos ringback-voice e ringback-alert além da habilidade watchdog. O mecanismo roda na imagem pré-construída (baixada na primeira chamada). Veja plugin/README.md.

Prefere sem Docker, ou quer o build nativo? Use o prompt de colar abaixo ou os passos manuais.

Deixe o Claude Code instalar para você

🤖 Caminho mais fácil: copie o prompt abaixo e cole no Claude Code — ele vai clonar, compilar, configurar e registrar tudo, pedindo apenas o que precisa (uma conta SIP gratuita + seu telefone para atender uma chamada de teste).

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

Prefere fazer manualmente? O início rápido e o passo a passo completo estão abaixo.

Início 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"

Passo a passo completo + referência de variáveis de ambiente: Configurar ringback-voice abaixo.

Ressalvas honestas (leia primeiro)

Multiplataforma. macOS (nativo), Linux (nativo), Windows (via WSL2 ou Docker). O mecanismo é headless — sem necessidade de placa de som. Windows nativo (MSVC) não é suportado intencionalmente; WSL2/Docker é o caminho para Windows.
Não é ChatGPT-realtime. O loop de voz é gravar → whisper STT → LLM → Piper/say TTS, então espere ~1–2 s por turno. É um walkie-talkie confiável com barge-in, não uma voz realtime em streaming.
O recurso de voz depende de software GPL (pjproject/pjsua2). Este repositório é Apache-2.0, mas redistribuir um pacote que vincula pjsua2 carrega obrigações GPL — veja NOTICE. O servidor ringback-alert não é afetado.
Sua máquina deve estar ligada e online, e para uma chamada de voz uma sessão do Claude deve estar ativa (é o cérebro) durante a duração.
Barge-in assume baixo eco acústico (mono ou headset). No viva-voz, o TTS pode ecoar no microfone e disparar falsamente "interrupção." Não há cancelamento de eco neste caminho.
Realidade do push iOS: um push auto-hospedado/gratuito não pode realmente furar Focus/Silent no iPhone exceto via Critical Alerts do Pushover (pago) — veja as notas do ringback-alert abaixo.

Arquitetura

  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

O ringback-alert é mais simples: ele chama ntfy/Pushover HTTP e/ou baresip para um toque SIP + mensagem de chat.

Pré-requisitos

Um dos:
- macOS (Apple Silicon ou Intel) com Homebrew — execute ./setup.sh
- Linux (Debian/Ubuntu/Fedora) — execute ./setup-linux.sh (veja docs/SETUP_LINUX.md)
- Windows — WSL2 (execute ./setup-linux.sh dentro dele) ou Docker Desktop (veja docs/SETUP_WINDOWS.md)
- Qualquer SO com Docker — docker build -t ringback . (veja docs/SETUP_DOCKER.md)
Uma conta Linphone SIP gratuita (sip.linphone.org) e o aplicativo Linphone iOS/Android (para os recursos de toque/voz)
Python 3.10+ (os bindings pjsua2 são compilados contra o python3 que você apontar)

Configurar ringback-voice — 4 passos

1. Clone + instale tudo:

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

setup.sh instala o toolchain, compila pjsua2 do código-fonte (~20–30 min — não existe fórmula Homebrew para os bindings), religa as dylibs do pjproject a um namespace OpenSSL de dois níveis (a correção do macOS que faz SIP/SRTP funcionar), baixa o modelo whisper, instala Piper + uma voz, instala dependências, e cria voice.env para você. Seguro para reexecutar. (Substitua PYTHON_BIN / PJPROJECT_DIR / WHISPER_MODEL_NAME se seu layout for diferente.)

No Linux? Use ./setup-linux.sh em vez disso — ele faz o mesmo build com apt/dnf e não precisa de religação OpenSSL. No Windows? Use WSL2 (docs/SETUP_WINDOWS.md) ou Docker. Registre o servidor com o lançador multiplataforma python3 run_voice_mcp.py (o .sh é apenas para macOS).

Encontrou um problema no macOS? docs/SETUP_MACOS.md é um guia de causa-raiz + solução de problemas testado em campo (alvo de build, a correção do flat-namespace OpenSSL, modelo whisper, tabela sintoma→correção).

2. Obtenha uma conta SIP gratuita (este é o telefone que toca):

Cadastre-se em https://subscribe.linphone.org (ou toque em Criar conta no aplicativo Linphone). Você recebe um nome de usuário e senha; seu endereço é sip:<username>@sip.linphone.org.
Instale o aplicativo Linphone no seu iPhone, entre e confirme que mostra Conectado.

3. Preencha voice.env (já criado pelo setup.sh — apenas edite). Apenas três variáveis são obrigatórias:

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

Referência completa de variáveis:

Variável	Obrigatória	Padrão	O que é
`VOICE_SIP_ID`	✅	—	Seu endereço SIP, ex. `sip:you@sip.linphone.org`
`VOICE_SIP_USER`	✅	—	Nome de usuário SIP (a parte antes de `@`)
`VOICE_SIP_PASS`	✅	—	Sua senha SIP
`VOICE_SIP_CALLEE`	—	= `VOICE_SIP_ID`	Endereço para chamar (normalmente você mesmo)
`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` (padrão) · `medium.en` (preciso)
`VOICE_TTS`	—	`auto`	Mecanismo TTS: `auto` (Piper se instalado, senão voz do SO) · `piper` · `say` · `espeak` · `sapi`
`VOICE_PIPER_MODEL`	—	`~/.piper-voices/en_US-lessac-medium.onnx`	Voz Piper (`.onnx`; precisa do `.onnx.json` correspondente ao lado)
`VOICE_TTS_CMD`	—	—	Modelo de comando TTS personalizado com `{text}`/`{out}` (substitui `VOICE_TTS`)
`VOICE_NULL_AUDIO`	—	`auto`	Forçar dispositivo de áudio nulo pjsua2 (`auto` = ligado exceto macOS; `1`/`0` para forçar)
`RINGBACK_PRESENCE`	—	—	Substituir idle/presença do watchdog: `present` ou `absent` (para Wayland/headless)
`PJPROJECT_DIR`	—	`~/build/pjproject-2.17`	Diretório de build pjsua2 (auto-detectado)
`PYTHON_BIN`	—	`$(command -v python3)`	Python que tem pjsua2 (auto-detectado)
`OPENSSL_PREFIX`	—	`$(brew --prefix openssl@3)`	Bibliotecas OpenSSL (macOS; auto-detectado)

4. Registre + teste:

# 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

Então em uma sessão nova do Claude diga: "Use ringback-voice para me ligar e dizer olá." Seu telefone deve tocar.

Claude Desktop em vez de Code? Adicione isso ao ~/Library/Application Support/Claude/claude_desktop_config.json (caminho absoluto obrigatório; reinicie o aplicativo):
{ "mcpServers": { "ringback-voice": { "command": "/absolute/path/to/ringback/run_voice_mcp.sh" } } }

Configurar ringback-alert (opcional)

O ringback-alert lê sua configuração do bloco env do cliente MCP (sem arquivo para originar). Registre-o com os canais que desejar:

# 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

Veja alert.env.example para todas as variáveis (ntfy / Pushover / toque SIP). Use um tópico ntfy longo e aleatório — qualquer um que o conheça pode ler/publicar.

Usando ringback-voice (a conversa)

O LLM dirige um loop simples:

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) fala enquanto escuta. Se você falar por cima, ele para imediatamente e diz ao LLM até onde chegou e o que você disse (barge-in).
get_conversation() retorna a transcrição completa até agora — ambos os lados, mais onde foi interrompido.
O TTS lê texto literalmente, então as descrições das ferramentas instruem o modelo a falar resumos em linguagem simples, nunca logs/códigos brutos — esses vão via alert_me como texto.

Trade-off de precisão/velocidade do modelo Whisper (defina WHISPER_MODEL): base.en (rápido/aproximado) → small.en (equilibrado, padrão) → medium.en (mais preciso/lento).

Usando ringback-alert (notificações)

alert_me(message, severity, title) com severity = info | warn | critical. Canais via ALERT_CHANNEL (lista separada por vírgulas de ntfy, pushover, call):

ntfy — push gratuito; alto mas não fura iOS Focus/Silent a menos que seja na lista de permissões por Focus.
Pushover — $5 único; verdadeiros Critical Alerts iOS (fura Focus/Silent, repete até reconhecer) em critical.
call — toque SIP gratuito + mensagem de chat Linphone via baresip; toca em tela cheia, apenas em critical por padrão.

Um guarda de limite de taxa embutido (padrão 5/60s, por processo) impede que um chamador com defeito te spamme.

Habilidade incluída: watchdog

skills/watchdog/ é uma habilidade Claude pronta para usar construída nesses servidores. Ela observa uma condição que você dá (uma execução de CI, um deploy, um pod, um arquivo) e escala apenas quando você está realmente longe do laptop — status do chat → aviso no chat → push ringback-alert → chamada ringback-voice — julgado pelo tempo de inatividade de entrada (macOS, Linux ou Windows; veja platform_compat.hid_idle_seconds). Ela nunca interrompe você enquanto digita, e desescala no momento em que você toca o teclado.

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

Então: /watchdog <what to watch> | priority=<low|medium|critical> — low = apenas chat, medium = pode enviar alerta de telefone, critical = pode fazer uma chamada. Design completo em skills/watchdog/SKILL.md.

Segurança

As credenciais SIP residem apenas no seu arquivo local voice.env ignorado pelo git (e no arquivo accounts do baresip para o alerta de ringback) — nunca no repositório ou na configuração do cliente MCP, quando possível evitá-lo.
O servidor de voz apenas chama o único URI SIP que você configura — ele não pode discar números arbitrários.
Trate os tópicos do ntfy como segredos (use um tópico aleatório longo); não coloque detalhes sensíveis nos corpos dos alertas no ntfy.sh público.
Consulte NOTICE para a ressalva de licenciamento GPL/pjproject antes de redistribuir.

Licença

Apache-2.0 (veja LICENSE), com uma ressalva importante de GPL para a dependência pjproject do componente de voz — veja NOTICE.

Créditos

Construído sobre pjproject/pjsua2, whisper.cpp, baresip, ntfy e Linphone.