WhatsApp Evolution API — MCP Server

Servidor Model Context Protocol (MCP) que expõe a Evolution API v2 para assistentes de IA (Claude Desktop, Claude Code, Cursor). Gerencia instâncias de WhatsApp, envia mensagens, configura Typebot e webhooks.

Versão single-tenant: uma Evolution API, uma chave global, sem banco de dados, sem billing, sem OAuth. Transporte SSE sobre Express.

Origem: extraído do commit c4bc066 do repositório whatsapp-connector, antes de ele virar produto multi-tenant.

---

Variáveis de ambiente

Variável	Obrigatória	Descrição
EVOLUTION_API_URL	✅	Endpoint da Evolution API v2, sem barra no final
EVOLUTION_GLOBAL_KEY	✅	Chave global (admin). Dá acesso a todas as instâncias
PORT	❌	Porta HTTP. Default 3000

Copie .env.example para .env e preencha. O processo aborta no boot se as duas obrigatórias faltarem.

---

Rodando local

npm install
npm run build
npm start

Ou em watch, sem build:

npm run dev

Endpoints:

• GET /health → {"status":"ok","transport":"sse","sessions":N}
• GET /sse → abre a conexão SSE (o cliente MCP conecta aqui)
• POST /messages?sessionId=... → canal de volta do MCP

---

Deploy no Easypanel

1. Criar o serviço — App → Create Service → App.
2. Source — aponte para este repositório Git (branch main).
3. Build — método Dockerfile, path ./Dockerfile. O build é multi-stage e a imagem final roda como usuário não-root com apenas as dependências de produção.
4. Environment — adicione:

   EVOLUTION_API_URL=https://evolutionapi.landcriativa.com
   EVOLUTION_GLOBAL_KEY=<sua-chave-global>
   

   Não defina PORT — o Easypanel injeta a dele e o código respeita.
5. Domains — exponha a porta 3000, ative HTTPS e anote o domínio gerado.
6. Deploy. O healthcheck do container bate em /health; se ficar verde, subiu.

Conferindo

curl https://SEU-DOMINIO/health

Nota sobre SSE atrás de proxy

O transporte SSE mantém a conexão HTTP aberta. Se o cliente MCP cair sozinho depois de alguns minutos, aumente o timeout de proxy do serviço no Easypanel (Advanced → Proxy) — o default costuma ser curto demais para conexões longas.

---

Registrando no cliente de IA

Claude Desktop (claude_desktop_config.json)

Local, rodando o build da máquina:

{
  "mcpServers": {
    "whatsapp-evolution": {
      "command": "node",
      "args": [
        "D:/Códigos/Tzolkin/Projetos/Produtos Tzolkin/mcps_personalizados/whatsapp-mcp-evolution/build/index.js"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolutionapi.landcriativa.com",
        "EVOLUTION_GLOBAL_KEY": "sua-chave-global"
      }
    }
  }
}

Remoto, apontando para o Easypanel:

{
  "mcpServers": {
    "whatsapp-evolution": {
      "url": "https://SEU-DOMINIO/sse"
    }
  }
}

Claude Code

claude mcp add --transport sse whatsapp-evolution https://SEU-DOMINIO/sse

⚠️ Este servidor não tem autenticação. Qualquer um que alcance /sse controla o WhatsApp com a chave global. Se for expor publicamente, ponha um proxy com auth na frente ou restrinja por IP.

---

Ferramentas disponíveis

Categoria	Ferramenta	Descrição
Instância	list_instances	Lista instâncias e status de conexão
Instância	create_instance	Cria uma nova instância de WhatsApp
Instância	connect_instance	Retorna QR Code / dados de emparelhamento
Instância	get_instance_status	Status da conexão (CONNECTED, DISCONNECTED…)
Instância	logout_instance	Desconecta a sessão ativa
Instância	delete_instance	Exclui a instância do servidor
Mensagens	send_text	Envia texto para contatos ou grupos
Mensagens	send_media	Envia imagem, vídeo, áudio ou documento (URL ou Base64)
Mensagens	get_messages	Histórico de mensagens da instância (exige banco habilitado na Evolution)
Typebot	configure_typebot	Configura e ativa a integração do Typebot
Typebot	get_typebot_settings	Exibe as configurações atuais do Typebot
Typebot	change_typebot_status	Abre, pausa ou fecha a sessão de atendimento
Typebot	start_typebot_flow	Inicia manualmente um fluxo para um contato
Webhook	configure_webhook	Configura webhooks de notificação/recebimento
Webhook	get_webhook_settings	Consulta os webhooks configurados