WACrew

Guia

Problemas na instalação do whatsapp-mcp e como resolver

Erros comuns ao instalar o lharries/whatsapp-mcp e os forks: CGO no Windows, uv não encontrado, QR que não aparece, limite de aparelhos, histórico vazio e banco fora de sincronia.

Atualizado em 3 min de leitura
Nesta página
  1. "Binary was compiled with CGO_ENABLED=0, go-sqlite3 requires cgo to work"
  2. O cliente diz que o servidor não subiu, ou "uv: command not found"
  3. As ferramentas aparecem, mas voltam vazias
  4. O QR não aparece
  5. "Device limit reached"
  6. Mensagens fora de sincronia
  7. Pediu QR de novo depois de umas semanas
  8. Nota de voz que não toca
  9. Quando parar de brigar com a instalação
  10. Perguntas frequentes

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

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.