whatsapp-mcp

MCP server que dá a agentes IA visão e escrita no WhatsApp do macOS — o paralelo do chrome-devtools MCP para o Chrome, aplicado ao app nativo.

• Ver: histórico completo (banco local ChatStorage.sqlite, read-only), busca, exportação. 834k+ mensagens, offline, sem tocar no app.
• Escrever: rascunho pre-preenchido via URL scheme + Enter com confirmação explícita (gate). Nada é enviado sem aprovação.
• Seguro por design: nunca grava no banco (gravar corrompe o Core Data e não transmite nada), zero protocolo não-oficial (sem Baileys/whatsmeow → sem risco de banimento), dados 100% locais.

Requisitos

• macOS (com o app WhatsApp nativo instalado e logado)
• Python 3.12+ e uv
• Permissão de Acessibilidade para o terminal/processo que roda o server (necessária apenas para o Enter do envio; leitura não precisa)

Instalação

1 linha (via PyPI):

uvx whatsapp-mcp-local

Ou local (desenvolvimento):

git clone https://github.com/Pl3ntz/whatsapp-mcp ~/dev/personal/whatsapp-mcp
cd ~/dev/personal/whatsapp-mcp
uv sync

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. O server anota as tools com readOnlyHint/destructiveHint, então send_message e confirm_send 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 no projeto:

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

Tools

Modelo de segurança (importante)

1. Leitura: sempre mode=ro; o banco nunca é modificado (testes verificam hash antes/depois).
2. Escrita em 2 passos: send_message só preenche o campo (comportamento do próprio WhatsApp, sem Enter → sem envio). O envio exige confirm_send ou Enter manual do proprietário.
3. Nunca gravar 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; apenas o que o proprietário pedir vai para o modelo.

Testes

uv run pytest

Roadmap

• Leitura (list/get/search/export) + escrita com gate — validado E2E
• Annotations MCP (readOnly/destructive) para gate no cliente
• Driver web (web.whatsapp.com via CDP) como segundo adapter
• Publicação (PyPI + registro) para instalação uvx whatsapp-mcp

Aviso

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