whatsapp-mcp-local

MCP server que dá a agentes IA visão e escrita no WhatsApp — o paralelo do chrome-devtools MCP para o WhatsApp.

• Ver: conversas, mensagens e histórico completo.
• Escrever: rascunho pre-preenchido + Enter com confirmação explícita (gate). Nada é enviado sem aprovação.
• Seguro por design: zero protocolo não-oficial (sem Baileys/whatsmeow → sem risco de banimento), dados locais.

Plataformas (auto-detect)

O server escolhe o driver automaticamente. Force com WHATSAPP_DRIVER=local|web|auto.

Requisitos

• Python 3.12+ e uv
• Driver local (macOS): app WhatsApp nativo instalado e logado + permissão de Acessibilidade para o processo (só para o Enter do envio)
• Driver web (qualquer SO): Google Chrome instalado. Na primeira execução, escaneie o QR uma vez (o MCP abre o Chrome com perfil dedicado; depois o login é permanente)

Instalação

uvx whatsapp-mcp-local

Integração com opencode

Adicione em ~/.config/opencode/opencode.json (ou opencode.json do projeto):

{
  "mcp": {
    "whatsapp": {
      "type": "local",
      "command": ["uvx", "whatsapp-mcp-local"],
      "enabled": true
    }
  }
}

Reinicie o opencode. As tools send_message e confirm_send são marcadas destructive e pedem confirmação por padrão no cliente.

Integração com Claude Code

claude mcp add whatsapp-mcp -- uvx whatsapp-mcp-local

Ou via .mcp.json:

{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "uvx",
      "args": ["whatsapp-mcp-local"]
    }
  }
}

Tools

Modelo de segurança

1. Leitura: mode=ro sempre; o banco nunca é modificado (testes verificam hash antes/depois).
2. Escrita em 2 passos: send_message só preenche o campo — sem Enter, sem envio (comportamento do próprio WhatsApp). O envio exige confirm_send ou Enter manual.
3. Nunca grava em ChatStorage.sqlite/Axolotl.sqlite (cripto) — corrompe o app e não transmite ao servidor.
4. JIDs mascarados nos outputs; textos truncados por config.
5. Dados processados localmente; só o que o proprietário pedir vai para o modelo.

Testes

uv run pytest

Roadmap

• Driver local (macOS) — validado E2E
• Driver web (cross-platform via Chrome CDP) — implementado e testado com mocks
• Auto-detecção de driver
• Publicado no PyPI (uvx whatsapp-mcp-local) e GitHub
• Validação E2E do driver web com QR logado (manual, depende de escanear QR 1x)

Aviso

Ferramenta para uso pessoal com a própria conta. O schema do banco e o DOM do web.whatsapp.com são do WhatsApp e podem mudar entre versões. Não use para enviar mensagens em nome de terceiros ou para fins não autorizados.