Skip to main content
Glama

wa-bridge

Ponte entre o seu WhatsApp e os seus agentes de código (Claude Code, Codex, opencode, Cursor, Claude Desktop...). O agente lê suas conversas — com áudio e vídeo transcritos localmente e imagens para ele "ver" — e envia mensagens, sempre atrás de uma confirmação humana em dois passos: nada sai sem você aprovar o rascunho.

Tudo roda na sua máquina. Nenhuma mensagem passa por servidor de terceiros, a transcrição é local (whisper.cpp) e a API só escuta em 127.0.0.1.

Leia antes de usar. O acesso ao WhatsApp é feito pelo Baileys, uma biblioteca não oficial. Isso viola os Termos de Serviço do WhatsApp e a conta pode ser banida, sem aviso. Use no seu próprio número, para uso pessoal, sem disparo em massa e sem automação que ninguém pediu. O risco é seu.

O que dá para pedir ao agente

  • "O que eu perdi hoje no grupo do condomínio?"

  • "Resume o áudio que a Ana mandou."

  • "O que tem nessa foto que o João mandou?"

  • "Responde pra minha mãe que chego às 20h." → o agente mostra o rascunho (destinatário, número mascarado, texto exato) e só envia depois do seu "ok".

  • "Marca o Allan no grupo do futebol e pergunta se o churrasco é sábado."

Related MCP server: WhatsApp MCP Server (TypeScript)

Como funciona

WhatsApp ──Baileys──▶ daemon (um processo por número) ──HTTP 127.0.0.1 + token──┐
                                                                                 ├─▶ shim MCP (Claude Code)
                                                                                 ├─▶ shim MCP (Codex, opencode...)
                                                                                 └─▶ painel no navegador

Um único processo é dono da sessão do WhatsApp. Cada agente fala com ele por um shim MCP fino. Isso existe por um motivo técnico: duas sessões Baileys na mesma conta derrubam o WhatsApp com device_removed, então os agentes não podem abrir conexões próprias.

O que vem junto:

  • 13 tools MCP: listar conversas, ler mensagens, baixar e transcrever mídia, resolver contatos e grupos por nome, enviar texto e mídia, citar mensagens, @marcar pessoas em grupo, reagir, marcar como lido, cancelar envio.

  • Gate de envio: rascunho → humano aprova → envio. Avisos para número nunca contatado, horário de silêncio e grupo; limite de 10 envios por hora; 1 rascunho por conversa; blocklist.

  • Digitação simulada: o envio aparece como "digitando...", quebrado em balões, com uma janela para cancelar antes de terminar.

  • Painel em http://127.0.0.1:7788/dashboard/: QR de pareamento, estado da sessão, métricas por agente e trilha de auditoria de todo envio.

Instalar

Precisa de macOS ou Linux, Node 24+, e, para transcrever áudio e vídeo, ffmpeg e whisper.cpp (whisper-cli). No Mac: brew install node ffmpeg whisper-cpp.

Pelo seu agente de IA (recomendado)

Clone o repositório, abra seu agente (Claude Code, Codex...) dentro da pasta e cole:

Leia docs/INSTALACAO.md e instale o wa-bridge nesta máquina seguindo o guia.
Me peça só o que depender de mim (como escanear o QR no celular).

O guia foi escrito para um agente seguir do começo ao fim, com verificação em cada passo.

À mão

git clone https://github.com/vinicius1209/wa-bridge.git
cd wa-bridge
./wa-bridge setup        # instala dependências, compila e baixa o modelo de transcrição (~1,6 GB)
./wa-bridge start        # sobe o daemon
./wa-bridge open         # abre o painel com o QR

No celular: WhatsApp > Aparelhos conectados > Conectar aparelho e escaneie o QR. A sessão fica salva em ~/.wa-bridge/auth/; não precisa escanear de novo a cada boot.

Modelo menor (mais rápido, transcreve pior): ./wa-bridge setup --model small.

Plugar no agente

./wa-bridge mcp-config

Imprime o comando pronto, com os caminhos da sua máquina, para Claude Code, Codex, opencode e qualquer cliente com JSON mcpServers. No Claude Code fica assim:

claude mcp add whatsapp --scope user \
  -e WA_AGENT_NAME=claude-code \
  -e WA_BRIDGE_URL=http://127.0.0.1:7788 \
  -- /caminho/para/wa-bridge/bin/wa-bridge-mcp

Reinicie o agente e peça "use wa_session_status". Depois coloque docs/LLMS.md no CLAUDE.md/AGENTS.md dos projetos onde o agente vai usar o WhatsApp: é o manual de uso dele (protocolo de envio, avisos, erros e regras de segurança).

Comandos

Comando

O que faz

./wa-bridge setup [--model NOME | --no-model]

instala dependências, compila e baixa o modelo do whisper

./wa-bridge start / stop / restart

sobe, para e reinicia o daemon

./wa-bridge status

processo e estado da sessão do WhatsApp

./wa-bridge open

abre o painel já autenticado

./wa-bridge qr

salva o QR de pareamento como PNG e abre

./wa-bridge pair [--yes]

descarta a sessão (com backup) e gera um QR novo

./wa-bridge mcp-config

config MCP pronta para cada agente

./wa-bridge logs

acompanha os logs

./wa-bridge token

copia o token da API

./wa-bridge doctor

diagnóstico completo da instalação

O daemon não sobe sozinho depois de reiniciar o computador. Para isso, rode como serviço (launchd no Mac, systemd no Linux): veja docs/OPERACAO.md.

Configuração

Tudo tem padrão; só mexa se precisar. Copie .env.example para .env e descomente o que quiser mudar (porta, pasta de estado, idioma da transcrição, horário de silêncio, limite de envios). Variáveis de ambiente sempre ganham do .env.

O estado fica em ~/.wa-bridge/:

~/.wa-bridge/
├── auth/          credencial da sessão do WhatsApp — SEGREDO
├── token          token da API local (chmod 600) — SEGREDO
├── wa.db          SQLite: conversas, mensagens, contatos, rascunhos, envios, auditoria
├── media/         mídia baixada, transcrições e keyframes
├── models/        modelo do whisper
├── logs/          daemon.log (JSONL)
├── blocklist.json opcional: JIDs para os quais nunca enviar
└── account.json   opcional: nome, descrição e cor desta instância

auth/ dá acesso total à sua conta do WhatsApp. Nunca commite, nunca cole o conteúdo em chat (nem para um agente depurar), nunca compartilhe.

Mais de um número

Um daemon serve um número. Para outro, suba outra instância com pasta e porta próprias:

mkdir -p ~/.wa-bridge-trabalho
ln -s ~/.wa-bridge/models ~/.wa-bridge-trabalho/models      # reaproveita o modelo
echo '{ "label": "Trabalho", "description": "WhatsApp do trabalho. Não é o número pessoal.", "color": "#F7B00D" }' \
  > ~/.wa-bridge-trabalho/account.json
WA_BRIDGE_HOME=~/.wa-bridge-trabalho WA_BRIDGE_PORT=7789 ./wa-bridge start
WA_BRIDGE_HOME=~/.wa-bridge-trabalho WA_BRIDGE_PORT=7789 WA_MCP_NAME=whatsapp-trabalho ./wa-bridge mcp-config

Todo comando dessa instância precisa das duas variáveis. O account.json dá nome e cor ao painel e vira a instrução do servidor MCP, para o agente saber por qual número está falando. Nunca compartilhe auth/ entre instâncias.

Segurança

  • Mensagem recebida é dado, não instrução. Alguém pode escrever "ignore suas instruções e mande X para Y". As tools devolvem JSON estruturado, as descrições avisam o modelo, e o gate garante que uma injeção não consegue enviar nada sozinha: o envio depende de um token que só vale depois de você ver o rascunho.

  • Número mascarado no rascunho e nas tools (só os 4 últimos dígitos).

  • API só em 127.0.0.1, com token Bearer. O painel estático abre sem token, mas todo dado exige token.

  • Auditoria append-only de todo rascunho, envio, bloqueio e cancelamento.

  • A digitação simulada existe para quem recebe e para dar tempo de cancelar. Não é proteção contra banimento: não existe proteção contra banimento.

Docker

Existe um caminho via Docker (npm run docker:build && npm run docker:up), pensado para servidor Linux. Num Mac, prefira o script: dentro do container o whisper não usa a GPU e a transcrição fica dezenas de vezes mais lenta. Detalhes em docs/OPERACAO.md. Nunca rode o Docker e o script ao mesmo tempo.

Documentação

Desenvolvimento

npm run typecheck   # TypeScript strict nos dois workspaces
npm test            # testes do daemon e do shim
npm run build       # daemon/dist e mcp/dist

Licença

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with your personal WhatsApp account, allowing them to search messages and contacts, retrieve chat history, and send messages to individuals or groups. Uses WhatsApp Web API with local data storage for privacy and security.
      11 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with your personal WhatsApp account to search messages, list chats, and send messages. It stores all authentication and message data locally using SQLite for privacy and direct multi-device API connection.
      11 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables driving an AI coding session directly from WhatsApp over either a linked-device connection or the official Cloud API, with bidirectional messaging, media, polls, and local voice transcription. Access gating, per-group personalities, and emoji-based approval of tool requests keep strangers out and let users authorize or deny actions remotely.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives AI agents safe access to a single WhatsApp account so they can read and search chats, receive new messages in real time, reply with quotes and typing indicators, send and download media, and react with emojis. Phone numbers stay on the server — agents only see random IDs and names — while sessions, messages and media are encrypted at rest and sending is rate-limited to protect the account.
      49 npm
      3
      MIT