wa-bridge
Enables interaction with the user's WhatsApp account, including listing conversations, reading messages, resolving contacts and groups, downloading and locally transcribing audio/video, viewing images, and sending text/media with human-approved send gates, mentions, reactions, and read receipts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 navegadorUm ú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 QRNo 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-configImprime 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-mcpReinicie 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 |
| instala dependências, compila e baixa o modelo do whisper |
| sobe, para e reinicia o daemon |
| processo e estado da sessão do WhatsApp |
| abre o painel já autenticado |
| salva o QR de pareamento como PNG e abre |
| descarta a sessão (com backup) e gera um QR novo |
| config MCP pronta para cada agente |
| acompanha os logs |
| copia o token da API |
| 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ânciaauth/ 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-configTodo 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
docs/INSTALACAO.md: instalação passo a passo, escrita para um agente seguir.docs/LLMS.md: manual das tools para o agente que vai usar o WhatsApp.docs/OPERACAO.md: serviço, Docker, pareamento, troubleshooting, backup.docs/ARQUITETURA.md: arquitetura, contratos, schema e API HTTP (leia antes de mudar o código).
Desenvolvimento
npm run typecheck # TypeScript strict nos dois workspaces
npm test # testes do daemon e do shim
npm run build # daemon/dist e mcp/distLicença
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read, search and reply to your WhatsApp chats from your AI, using your own number.
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm1ISC
- AlicenseNot gradedqualityAmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceGives 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 npm3MIT