whatsapp-mcp

MCP local que conecta o WhatsApp ao Claude via QR code.
Usa o protocolo oficial Multidevice (o mesmo do WhatsApp Web) — sem modificar o app, criptografia preservada.

---

Instalação rápida

1. Pré-requisitos

• Node.js 18+ instalado
• WhatsApp no celular

2. Clonar e instalar

git clone https://github.com/PedroSodrr10/mcp-whatsapp-claude.git
cd mcp-whatsapp-claude
npm install

3. Parear o celular (única vez por computador)

npm run pair

Uma página vai abrir automaticamente em http://localhost:3000 com o QR code.

No celular:

1. Abra o WhatsApp
2. Toque em ⋮ → Dispositivos vinculados
3. Toque em Vincular dispositivo
4. Aponte a câmera para o QR code

A página mostrará "Conectado!" quando terminar.
A sessão fica salva em session/ — não é preciso repetir este passo.

4. Registrar no Claude

Adicione o bloco abaixo ao .mcp.json do seu projeto (ou à configuração global do Claude):

{
  "mcpServers": {
    "whatsapp": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/CAMINHO/PARA/mcp-whatsapp-claude/index.js"]
    }
  }
}

Substitua C:/CAMINHO/PARA/ pelo caminho real onde você clonou o repositório.
No Windows, tanto / quanto \\ funcionam no JSON.

Reinicie o Claude — as ferramentas do WhatsApp aparecerão automaticamente.

---

Ferramentas disponíveis

Ferramenta	O que faz
list_chats	Lista conversas recentes
list_contacts	Lista contatos da agenda
get_messages	Mensagens de um chat (use list_chats para obter o ID)
search_messages	Busca por palavra-chave no histórico local
send_message	Envia mensagem 1:1 com rate limiter automático
get_contact_info	Nome e JID de um número

---

Limites de envio (anti-ban)

O MCP bloqueia automaticamente qualquer envio acima destes limites:

• Máximo 5 mensagens por minuto
• Máximo 100 mensagens por dia
• Apenas 1:1 — sem listas de transmissão, sem disparo em massa

---

Mover para outro computador

git clone https://github.com/PedroSodrr10/mcp-whatsapp-claude.git
cd mcp-whatsapp-claude
npm install

• Copie a pasta session/ do computador anterior para não repetir o QR.
• Ou rode npm run pair de novo para parear do zero.
• Atualize o caminho no .mcp.json.

---

Solução de problemas

Problema	Solução
Página não abre	Acesse http://localhost:3000 manualmente no navegador
QR expira antes de escanear	Recarregue a página — um novo QR é gerado
"Sessão não encontrada"	Execute npm run pair primeiro
Sessão expirada / desconectado	Apague session/ e execute npm run pair de novo
Claude não vê as ferramentas	Verifique o caminho absoluto no .mcp.json e reinicie o Claude

---

Estrutura do projeto

mcp-whatsapp-claude/
├── index.js          ← entrada do MCP (Claude chama este arquivo)
├── pair.js           ← pareamento via QR na web (rodar uma vez)
├── src/
│   ├── client.js     ← conexão com WhatsApp via Baileys
│   ├── tools.js      ← ferramentas expostas ao Claude
│   └── rate-limiter.js  ← proteção anti-ban
├── session/          ← credenciais (criado automaticamente, não vai ao git)
└── mcp-config-example.json  ← snippet pronto para o .mcp.json