Como conectar o Claude no WhatsApp com Evolution API

Imagina conversar com o Claude — e não só isso, deixar ele rodar comandos, editar arquivos e executar tarefas reais no seu servidor — direto pelo WhatsApp. É exatamente isso que a bridge wpp-claude faz: um middleware em Python que liga o Claude Code CLI ao WhatsApp via Evolution API, com aprovação interativa de cada ação sensível.

Neste tutorial você vai montar tudo do zero: Evolution API rodando, bridge em FastAPI configurada, webhook recebendo mensagens, e o Claude respondendo no seu chat. No final você terá um assistente IA que obedece você pelo WhatsApp — e pede permissão antes de fazer qualquer coisa destrutiva.

Arquitetura: como as peças se conectam

Antes do código, o mapa mental. O fluxo é simples quando você entende quem fala com quem:

• Evolution API: conecta sua conta do WhatsApp (via Baileys) e envia/recebe mensagens.
• Bridge FastAPI: recebe o webhook da Evolution, passa o texto pro Claude e devolve a resposta.
• Claude Code CLI: processa o prompt com seu contexto e ferramentas.
• MCP (Model Context Protocol): expõe a ferramenta approval_prompt que envia uma enquete interativa pro WhatsApp antes de qualquer ação sensível (Write, Edit, Bash) — parece com isso:

Pré-requisitos

• Python 3.10+ instalado
• Claude Code CLI autenticado (claude --version deve funcionar)
• Docker (pra Evolution API) ou uma instância já rodando
• Um número WhatsApp pra usar como bot — obrigatoriamente um chip dedicado, nunca o seu pessoal. Tem um aviso sobre risco de ban no final do post pra entender o porquê.
• Um túnel público se estiver em localhost: ngrok, Cloudflare Tunnel ou similar

Passo 1 — Evolution API rodando

Se você ainda não tem a Evolution no ar, a forma mais rápida é com Docker:

docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=sua_chave_super_secreta \
  -e DATABASE_ENABLED=false \
  atendai/evolution-api:latest

Depois crie uma instância e pareie seu número via QR Code:

# criar instância
curl -X POST http://localhost:8080/instance/create \
  -H "apikey: sua_chave_super_secreta" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"claude-bot","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'

# pegar QR code pra parear
curl http://localhost:8080/instance/connect/claude-bot \
  -H "apikey: sua_chave_super_secreta"

Abra o WhatsApp do seu número-bot → Aparelhos conectados → escaneie o QR Code retornado. Pronto, instância online.

Passo 2 — Clonar e configurar a bridge

git clone https://github.com/gitsevero/wpp-claude.git
cd wpp-claude/claude_bridge_py

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/Mac:
# source .venv/bin/activate

pip install -r requirements.txt

As dependências são enxutas de propósito:

# requirements.txt
fastapi==0.115.0
uvicorn[standard]==0.30.6
httpx==0.27.2
python-dotenv==1.0.1

Passo 3 — Variáveis de ambiente

Copie o template e edite os valores:

cp .env.example .env

Conteúdo do .env:

EVO_URL=http://localhost:8080
EVO_APIKEY=sua_chave_super_secreta
EVO_INSTANCE=claude-bot
PORT=3333
ALLOWED_NUMBERS=5551999999999
CLAUDE_TIMEOUT_MS=300000
CLAUDE_MODEL=sonnet

Cada variável em uma frase:

• EVO_URL — onde sua Evolution API está rodando.
• EVO_APIKEY — a API key definida ao subir o container.
• EVO_INSTANCE — nome da instância criada no passo 1.
• PORT — porta local da bridge (Evolution vai bater webhook aqui).
• ALLOWED_NUMBERS — lista de números (separados por vírgula) autorizados. Nunca deixe vazio em produção.
• CLAUDE_TIMEOUT_MS — timeout de execução do Claude por mensagem.
• CLAUDE_MODEL — sonnet, opus ou haiku.

Passo 4 — Rodar a bridge

python main.py

A bridge sobe um servidor FastAPI na porta 3333 com três responsabilidades:

1. Endpoint /webhook recebendo mensagens da Evolution.
2. Endpoint /mcp expondo o MCP server pro Claude chamar approval_prompt.
3. Orquestração: spawn do claude -p por conversa, streaming de resposta e envio de volta pro WhatsApp.

Passo 5 — Apontar o webhook da Evolution

Se sua bridge está em localhost:3333, exponha com ngrok:

ngrok http 3333

Pegue a URL pública (ex: https://abc123.ngrok-free.app) e configure o webhook da instância:

curl -X POST http://localhost:8080/webhook/set/claude-bot \
  -H "apikey: sua_chave_super_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://abc123.ngrok-free.app/webhook",
      "byEvents": false,
      "events": ["MESSAGES_UPSERT"]
    }
  }'

A partir daqui, toda mensagem recebida no número-bot dispara o webhook pra sua bridge.

Passo 6 — MCP e aprovação interativa

A sacada arquitetural do projeto está aqui. Quando o Claude recebe uma tarefa que envolve ferramentas sensíveis (criar arquivo, rodar bash, editar código), ele é iniciado com:

claude -p --mcp-config .mcp-config.json \
  --permission-prompt-tool mcp__wa__approval_prompt \
  "<mensagem do usuário>"

O arquivo .mcp-config.json registra a própria bridge como servidor MCP:

{
  "mcpServers": {
    "wa": {
      "type": "http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

Quando o Claude decide usar uma ferramenta perigosa, ele invoca mcp__wa__approval_prompt. A bridge intercepta, monta a enquete (mesma mostrada lá em cima) e envia pro seu WhatsApp. Você toca na opção. O webhook recebe a escolha, resolve a promise do MCP, e o Claude continua (ou aborta) a execução.

Simples, elegante, e resolve o maior problema de agentes autônomos: controle humano em loop.

Comandos úteis no chat

• /reset — limpa o histórico da conversa atual.
• sim / nao — fallback textual caso a lista interativa falhe em algum cliente.

Passo 7 — Testando no WhatsApp

Do seu WhatsApp pessoal (o número em ALLOWED_NUMBERS), mande pro bot:

Cria um arquivo hello.txt com o texto "funcionou" na pasta do projeto.

Você deve receber de volta uma lista interativa pedindo aprovação pra usar a tool Write. Toque em ✅ Sim. Segundos depois, o Claude responde confirmando a criação. Confira o arquivo no servidor — está lá.

Pronto. Você tem um agente IA no seu bolso, com salvaguardas.

Indo pra produção

Se a ideia é deixar isso rodando de verdade:

• Hospede em VPS (Hetzner, DigitalOcean, Oracle Free Tier) e troque o ngrok por um domínio com HTTPS via Caddy ou Nginx.
• Process manager: rode a bridge com systemd ou pm2 pra restart automático.
• Logs estruturados: adicione loguru e mande pra Grafana Loki ou Axiom.
• Rate limiting por número no webhook — evita loop infinito se alguém fizer bagunça.
• Sandbox: execute o claude -p dentro de um container Docker isolado por conversa. Isso limita o estrago máximo possível a um container descartável.
• Persistência: grave histórico em SQLite/Postgres por número pra manter contexto entre sessões.

Essa arquitetura — WhatsApp → Evolution → Bridge FastAPI → Claude CLI com MCP — é enxuta (quatro dependências Python, menos de 500 linhas de código) e resolve o problema certo: transformar o Claude num agente remoto, controlado por permissão humana, acessível de qualquer lugar.

Dá pra estender: trocar Claude por outro LLM, plugar RAG em cima da sua base de conhecimento, transformar em suporte N1 automatizado. O esqueleto é o mesmo.