Quase todo problema com o lharries/whatsapp-mcp e os forks vem da instalação em dois processos: uma ponte em Go que segura a sessão do WhatsApp e um servidor MCP em Python que o seu cliente inicia. Estes são os erros mais comuns, com a solução tirada das próprias notas do projeto.
"Binary was compiled with CGO_ENABLED=0, go-sqlite3 requires cgo to work"
Você está no Windows. O go-sqlite3 precisa de CGO e de um compilador C, e o CGO vem desligado lá. Instale um compilador (o README sugere o MSYS2, com a pasta ucrt64\bin no PATH) e rode:
cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go
O cliente diz que o servidor não subiu, ou "uv: command not found"
O JSON precisa de caminhos absolutos: a saída de which uv em command e o caminho completo de whatsapp-mcp-server em args. O Claude Desktop não carrega o PATH do seu terminal, então uv sozinho costuma falhar. Reinicie o cliente depois de editar a configuração.
As ferramentas aparecem, mas voltam vazias
Os dois processos precisam estar rodando. O servidor em Python lê o que a ponte em Go guarda. Sem a ponte de pé, a busca volta vazia e o envio falha. Logo depois do primeiro pareamento, o histórico pode levar alguns minutos para carregar.
O QR não aparece
Reinicie a ponte. Se o terminal não desenha o QR, tente outro. Se a sessão já existe, a ponte reconecta sem mostrar QR, e isso é o esperado.
"Device limit reached"
O WhatsApp limita os aparelhos conectados. Remova um antigo no celular, em Configurações, Aparelhos conectados, e conecte de novo.
Mensagens fora de sincronia
Pare a ponte, apague whatsapp-bridge/store/messages.db e whatsapp-bridge/store/whatsapp.db, suba de novo e escaneie. O histórico local se perde e volta a sincronizar a partir do que o celular mandar.
Pediu QR de novo depois de umas semanas
O README avisa que pode ser preciso autenticar de novo depois de uns 20 dias. Deixar a ponte rodando direto ajuda.
Nota de voz que não toca
Para chegar como nota de voz, o áudio precisa ser Ogg Opus. Com FFmpeg instalado, send_audio_message converte MP3 ou WAV; sem ele, send_file manda um arquivo de áudio comum.
Quando parar de brigar com a instalação
- Docker: o whatsapp-mcp-extended tem docker compose para a mesma arquitetura. Veja MCP de WhatsApp no Docker.
- Só Node: whatzmcp e WACrew rodam com
npx. O coletor do WACrew fica num servidor, então as mensagens chegam mesmo com o notebook fechado. Veja WhatsApp MCP sem Go.
Perguntas frequentes
Quem fala com o WhatsApp, o Python ou o Go? A ponte em Go. O servidor em Python só fala MCP e lê o banco ou chama a ponte.
Por que o agente não viu as mensagens de ontem à noite? O WhatsApp entrega cada mensagem aos aparelhos que estão online. Se a ponte estava desligada, elas podem não ter chegado ao banco. Um servidor ligado 24 horas resolve.
Essas soluções valem para os forks? Na maior parte, sim. verygoodplugins/whatsapp-mcp e whatsapp-mcp-extended seguem o mesmo desenho, com configurações extras.



