Skip to main content
Glama
brunotrolo

WhatsApp MCP

by brunotrolo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

WhatsApp MCP (Baileys puro)

Servidor MCP para um assistente (ex.: Claude) mandar alertas no WhatsApp pessoal do operador, com confirmação de entrega e observabilidade do canal. Usa Baileys diretamente (sem Evolution API, sem Postgres, sem Redis), rodando numa VM Compute Engine e2-micro sempre ligada (Always Free tier do Google Cloud — custo ~R$0/mês).

Por que VM e não Cloud Run? A sessão WhatsApp Web exige um WebSocket persistente; o Cloud Run congela a CPU do container entre requisições. Ver docs/ARQUITETURA.md.

📚 Documentação

Documento

Conteúdo

docs/ARQUITETURA.md

Arquitetura no Google Cloud (VM e2-micro, Caddy+sslip.io, IP estático, systemd), auth, deploy e custo.

docs/FERRAMENTAS.md

As 15 ferramentas MCP em detalhe (parâmetros, recomendadas × extras, confirmação de entrega).

docs/TROUBLESHOOTING.md

A saga de bugs e seus fixes (405, git ownership, 9º dígito, OAuth, timing de deploy…).

Este repositório é a fonte de verdade completa deste MCP — código, deploy e documentação. Não depende de nenhum outro repositório.

Related MCP server: WhatsApp MCP Server

Ferramentas

Toda ferramenta de envio confirma a entrega (espera o recibo do WhatsApp) e retorna { entregue, status, id }. Status: pendente → enviado_ao_servidor → entregue → lido. O ack de entrega independe de recibos de leitura; o lido é best-effort. GET /health expõe a mesma observabilidade (uptime check externo).

Recomendadas (sempre ligadas)

Ferramenta

O que faz

enviar_mensagem_whatsapp(texto)

Texto (aceita markdown do WhatsApp: *negrito*, _itálico_, ```mono```).

enviar_imagem_whatsapp(url|base64, legenda?)

Imagem — gráficos de payoff/curva de capital/IV Rank/print do cockpit.

enviar_documento_whatsapp(url|base64, nome_arquivo, legenda?)

PDF/CSV/XLSX — relatórios, auditoria, posições.

ler_mensagens_recebidas(limite?)

Two-way: lê as mensagens recebidas pelo robô (o operador comanda pelo WhatsApp; o assistente lê e age).

verificar_status_envio(id)

Reconfere entrega/leitura de um envio anterior.

verificar_status_conexao()

Observabilidade do canal (online? desde quando? última entrega OK?).

enviar_alerta_falado(texto, voz?)

Alerta falado: gera a fala do texto (Google TTS Neural pt-BR) e envia como nota de voz. Só aparece com GOOGLE_TTS_API_KEY configurada — ver setup em docs/FERRAMENTAS.md.

guia_de_uso(topico?)

Guia para a LLM: como usar as ferramentas complexas, com exemplos e boas práticas. A própria IA chama quando tem dúvida.

Extras (desligadas por padrão — atrás de HABILITAR_FERRAMENTAS_EXTRAS)

Implementadas para exploração futura; só aparecem/funcionam com HABILITAR_FERRAMENTAS_EXTRAS=true:

Ferramenta

O que faz

enviar_audio_whatsapp(url|base64, nota_de_voz?)

Envia áudio; com nota_de_voz=true manda como mensagem de voz (PTT — requer ogg/opus p/ tocar bem).

enviar_video_whatsapp(url|base64, legenda?)

Envia vídeo com legenda opcional.

enviar_sticker_whatsapp(url|base64)

Envia um sticker (idealmente webp).

responder_mensagem_whatsapp(id_recebida, texto)

Responde citando (reply/quote) uma mensagem recebida, pelo id de ler_mensagens_recebidas.

editar_mensagem_whatsapp(id, novo_texto)

Edita uma mensagem já enviada por este servidor (ex: marcar alerta como "resolvido").

apagar_mensagem_whatsapp(id)

Apaga para todos uma mensagem já enviada (retratar alerta falso).

reagir_mensagem_whatsapp(id, emoji)

Reage com emoji a uma mensagem (recebida ou enviada).

marcar_como_lida_whatsapp(id_recebida?)

Marca mensagens recebidas como lidas (uma específica, ou as últimas).

enviar_presenca_whatsapp(tipo)

Envia presença ao destino: composing (digitando), recording (gravando), paused, available, unavailable.

Para autorizar os extras (na VM):

echo 'HABILITAR_FERRAMENTAS_EXTRAS=true' | sudo tee -a /etc/systemd/system/whatsapp-mcp.env
sudo systemctl restart whatsapp-mcp

(abra uma conversa nova no claude.ai para as novas ferramentas aparecerem).

⚠️ Cada capacidade "bot-like" a mais aumenta o risco de banimento da conexão não-oficial. Para um canal pessoal de alertas, mantenha só o necessário ligado.

Dois números, dois papéis

  • Remetente (robô): número que escaneia o QR e mantém a sessão. Use um número secundário (reduz risco de banimento do principal).

  • Destino (WHATSAPP_DESTINO): onde os alertas chegam — seu número principal.

  • Se remetente == destino, a mensagem vai para o chat "Mensagem para mim". Use números diferentes.

Deploy

git clone https://github.com/brunotrolo/MCP_WhatsApp.git
cd MCP_WhatsApp
./scripts/deploy.sh

O script cria/atualiza a VM whatsapp-mcp-vm (projeto whatsapp-mcp-server-502704), o firewall, o IP estático e o HTTPS (Caddy + sslip.io). A VM roda um git pull deste mesmo repositório a cada (re)deploy — não há mais um passo separado de "publicar código": edite aqui, rode ./scripts/deploy.sh, pronto.

Se precisar reiniciar o serviço manualmente na VM, prefira scripts/restart-seguro.sh (dentro de /opt/whatsapp-mcp) em vez de systemctl restart direto — ver docs/TROUBLESHOOTING.md.

Endpoints

Método/rota

Descrição

POST /mcp/:key

MCP autenticado pela chave no path — é esta a URL usada no conector do claude.ai: https://<host>/mcp/<MCP_API_KEY>.

POST /mcp

MCP autenticado pelo header x-api-key (curl/testes).

GET /health

Público: { "status": "ok", "whatsapp": "conectado" | "reconectando" | "aguardando_qr" | "deslogado_precisa_novo_qr" }.

GET /pareamento/:key

Página web de repareamento — mostra status, QR (quando houver) e um botão "Reparear do zero". Não precisa de SSH/terminal: o botão apaga a sessão salva e reconecta o Baileys no mesmo processo. Use a mesma MCP_API_KEY: https://<host>/pareamento/<MCP_API_KEY>.

Variáveis de ambiente (/etc/systemd/system/whatsapp-mcp.env na VM)

Variável

Descrição

MCP_API_KEY

Chave exigida em /mcp (header) e /mcp/:key (path). Gerada no deploy.

WHATSAPP_DESTINO

Número de destino, só dígitos ou JID (5511999999999 ou ...@s.whatsapp.net). O código resolve o JID canônico via onWhatsApp() (trata o "9º dígito" do Brasil).

PORT

Porta interna do Node (padrão 8080; Caddy faz o HTTPS na frente).

HABILITAR_FERRAMENTAS_EXTRAS

true liga as ferramentas extras (áudio, vídeo, sticker, editar, apagar, reagir, responder, marcar_lida, presença). Padrão: desligado.

Pareamento (1ª vez / após logout)

gcloud compute ssh whatsapp-mcp-vm --project=<PROJECT_ID> --zone=us-east1-b
sudo journalctl -u whatsapp-mcp -f

Escaneie o QR com o celular remetente (WhatsApp → Aparelhos conectados → Conectar um aparelho). A sessão fica salva em auth_info_baileys e reconecta sozinha.

Troubleshooting

A saga de bugs (405, dubious ownership do git, 9º dígito, número errado, OAuth do conector, dessincronia de sessão @lid) está documentada em docs/TROUBLESHOOTING.md — leia antes de repetir os erros.

Licença

MIT — ver LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • WhatsApp MCP Server

    sjawhar
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to manage WhatsApp: list chats, send and receive messages, download media, and transcribe voice notes via the unofficial Baileys library.
    202 npm
    MIT

  • whatsapp-mcp-server

    rukman7
    A
    license
    A
    quality
    D
    maintenance
    Enables LLMs to interact with WhatsApp via the official WhatsApp Cloud API, providing tools for sending messages, templates, media, and managing conversations.
    13
    12 npm
    MIT

  • zaileys-mcp

    zeative
    A
    license
    B
    quality
    D
    maintenance
    Enables AI agents to control WhatsApp, including sending messages and media, reading chats, managing groups and communities, with QR/pairing auth and session persistence.
    14
    17 npm
    2
    MIT