# 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+](https://nodejs.org) instalado
- WhatsApp no celular

### 2. Clonar e instalar

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

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

```bash
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):

```json
{
  "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

```bash
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 |
| Conexão caiu no meio do uso | Normal — reconecta sozinho em alguns segundos (backoff automático) |
| "Sessão expirada" (WhatsApp deslogou de vez) | 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
```