WhatsApp MCP Server

Conecte seu WhatsApp ao Claude Desktop. Tudo permanece na sua máquina — sem nuvem, sem servidores

Documentação

WhatsApp MCP — Local

Conecte seu WhatsApp ao Claude Desktop. Tudo fica na sua máquina — sem nuvem, sem servidores, o desenvolvedor não vê nada.

📦 Todas as mensagens armazenadas em um banco de dados SQLite local (~/.whatsapp-mcp/whatsapp.db)
🔒 Chaves de autenticação armazenadas apenas em ~/.whatsapp-mcp/session/ — nunca saem da sua máquina
🔍 Pesquisa de texto completo em todo o histórico de conversas
📥 Importe conversas antigas pelo recurso Exportar Conversa do WhatsApp

Pré-requisitos

Node.js v20+ — baixe em nodejs.org (versão LTS)
Claude Desktop — baixe em claude.ai/download
Git — baixe em git-scm.com

Configuração (Máquina Nova)

Windows — instalador com duplo clique

Instale o Node.js LTS se ainda não tiver
git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
Abra a pasta clonada → clique duas vezes em install.bat

Pronto. O arquivo batch cuida de npm install e da configuração automaticamente. Sem PowerShell, sem edição manual.

Mac / Linux — terminal

git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
cd WhatsApp-MCP-Local
make install

Não tem make? Use: chmod +x install.sh && ./install.sh

Manual (qualquer plataforma)

npm install
npm run setup

Erro no PowerShell do Windows? Se aparecer "running scripts is disabled", execute isto uma vez no PowerShell e tente novamente:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Ou use install.bat — ele usa cmd.exe, que nunca tem esse problema.

A saída fica assim:

✅ Done! Config written:
   Server  : whatsapp
   Command : C:\Program Files\nodejs\node.exe
   Script  : C:\Users\You\WhatsApp-MCP-Local\src\index.ts

📋 Next steps:
   1. Fully quit Claude Desktop (system tray → Quit)
   2. Reopen Claude Desktop
   3. Your browser opens at http://localhost:3000 — scan the QR with WhatsApp
   4. Done! Use whatsapp_status in Claude to confirm.

Após a configuração

Feche e reabra o Claude Desktop
O navegador abre automaticamente em http://localhost:3000 — escaneie o QR
Aguarde alguns minutos para o histórico sincronizar

Acompanhe o progresso no Claude:

whatsapp_status
→ 📦 1,240 messages stored across 108 chats
→ 📅 History goes back to: 25/05/2025

Ferramentas Disponíveis

Ferramenta	O que faz
`whatsapp_status`	Status da conexão + estatísticas do banco de dados
`whatsapp_list_chats`	Todas as conversas ordenadas pelas mais recentes
`whatsapp_list_groups`	Apenas conversas em grupo
`whatsapp_find_contact`	Pesquise contatos por nome ou número de telefone
`whatsapp_get_messages`	Leia mensagens de uma conversa (histórico completo)
`whatsapp_send_message`	Envie uma mensagem
`whatsapp_search_messages`	Pesquisa de texto completo em todas as mensagens

Importar Conversas Antigas

O WhatsApp só envia o histórico recente durante a sincronização inicial. Para obter mensagens mais antigas:

Passo 1 — Exporte do seu celular

Abra a conversa no WhatsApp
Toque em ⋮ → Mais → Exportar Conversa
Escolha Sem Mídia
Envie o arquivo .txt para o seu computador

Passo 2 — Execute o importador

Primeiro encontre o JID do contato usando whatsapp_find_contact "Their Name" no Claude e depois:

npm run import -- "C:/path/to/WhatsApp Chat with John Doe.txt" "923001234567@s.whatsapp.net" "John Doe"

O importador mostra:

✅ Import complete!
   Contact  : John Doe
   Messages : 1,847 imported
   Range    : 15/03/2023 → 17/05/2026

📦 Database now has 3,091 messages across 109 chats

As mensagens são deduplicadas automaticamente — pode executar várias vezes com segurança.

Seus Dados

~/.whatsapp-mcp/
  session/          ← WhatsApp auth keys (never shared)
    creds.json
    pre-key-*.json
  whatsapp.db       ← All messages, searchable forever

Para desvincular do WhatsApp: Celular → Configurações → Dispositivos vinculados → encontre WhatsApp MCP → Sair. Depois exclua ~/.whatsapp-mcp/session/ e reinicie o Claude Desktop — você receberá um novo QR.

Para remover completamente: Exclua ~/.whatsapp-mcp/ e remova o bloco mcpServers da configuração.

Solução de Problemas

Erro "Server disconnected" no Windows: Certifique-se de ter usado tsx.cmd (não tsx) na configuração e que os caminhos usam / em vez de \.

O navegador não abre automaticamente: Acesse http://localhost:3000 manualmente.

As conversas aparecem como números em vez de nomes: Normal na primeira conexão — os nomes carregam conforme o WhatsApp sincroniza os contatos. Aguarde 30 segundos e verifique novamente.

Contato não encontrado: Use whatsapp_find_contact "name" — se mostrar "no messages synced yet", exporte a conversa e use o importador.