whatsapp-mcp-skill

WhatsApp MCP + Skill

Servidor MCP que conecta o seu WhatsApp ao Claude Code, mais uma skill /whatsapp que sabe ler mensagens, resumir o dia e enviar mensagens com confirmação.

Funciona como o WhatsApp Web: você vincula a sessão escaneando um QR code uma vez. A sessão fica salva localmente na sua máquina e nunca sai dela. Por baixo usa whatsapp-web.js rodando um Chrome headless.

Ferramentas

| Ferramenta | O que faz | |---|---| | whatsapp_list_chats | Lista chats recentes (nome, não lidas, última mensagem) | | whatsapp_get_messages | Lê mensagens de um chat por nome ou número | | whatsapp_send_message | Envia mensagem (exige match exato do nome do chat) | | whatsapp_daily_summary | Tudo que chegou hoje, agrupado por remetente |

Áudios são transcritos automaticamente se o Whisper estiver instalado (opcional).

Pré-requisitos

• Node.js 18+
• Google Chrome ou Chromium instalado
• (Opcional) Whisper para transcrição de áudio

Instalação

git clone https://github.com/alelopesjr-ai/whatsapp-mcp-skill.git ~/whatsapp-mcp-skill
cd ~/whatsapp-mcp-skill
npm install

1. Autenticar (vincular o WhatsApp)

node auth.js

Vai aparecer um QR code no terminal (e abrir uma imagem qr.png). No celular: WhatsApp > Dispositivos vinculados > Vincular dispositivo, escaneie. Quando aparecer Connected., pode fechar o terminal (Ctrl+C). A sessão fica salva em .wwebjs_auth/ (não versionada).

2. Registrar o MCP no Claude Code

claude mcp add whatsapp -- node ~/whatsapp-mcp-skill/index.js

Confira com claude mcp list. Troque ~/whatsapp-mcp-skill se você clonou em outro lugar.

3. Instalar a skill

Copie a skill para o seu projeto (ou para ~/.claude/skills/ para deixá-la global):

mkdir -p ~/.claude/skills/whatsapp
cp ~/whatsapp-mcp-skill/skill/SKILL.md ~/.claude/skills/whatsapp/SKILL.md

A skill assume o caminho de exemplo ~/whatsapp-mcp-skill. Se você clonou em outro lugar, ajuste os caminhos dentro do SKILL.md.

Pronto. No Claude Code, use /whatsapp ou peça em linguagem natural ("lê o que o fulano me mandou no zap").

Resolução de problemas

browser is already running / SingletonLock — sobrou um Chrome órfão segurando o lock. Geralmente basta tentar de novo. Se persistir:

pkill -f "whatsapp-mcp-skill/index.js"; pkill -f "wwebjs_auth/session"
rm -f ~/whatsapp-mcp-skill/.wwebjs_auth/session/Singleton*

auth_failure / pedindo QR de novo — a sessão caiu. Pare qualquer instância do servidor (pkill -f "whatsapp-mcp-skill/index.js") e rode node auth.js de novo.

Privacidade

Tudo roda localmente. A sessão (.wwebjs_auth/) fica só na sua máquina e está no .gitignore. Nenhuma mensagem passa por servidor de terceiros além da própria infra do WhatsApp.

Aviso

Isso usa uma biblioteca não oficial (whatsapp-web.js) que automatiza o WhatsApp Web. Não é endossado pelo WhatsApp/Meta. Use por sua conta e risco e com bom senso.