Evolution API MCP

MCP server para enviar e receber mensagens no WhatsApp direto do Claude Code, usando Evolution API (open-source, self-hosted).

O que faz

• Criar e gerenciar instancias WhatsApp

• Enviar mensagens de texto, midia, audio, localizacao, contatos, enquetes, stickers, botoes e listas

• Ler conversas e mensagens recebidas

• Reagir a mensagens, arquivar chats, marcar como lido

Opcao A — Railway (recomendado, sem Docker)

Deploy em nuvem em 5 minutos. Nao precisa de Docker nem servidor local.

1. Criar conta no Railway

Acesse railway.com e crie uma conta gratuita.

2. Deploy do template Evolution API

1. No Railway, clique em New Project

2. Clique em Deploy a template

3. Pesquise Evolution API (o template com mais de 2000 projetos — tem Postgres + Redis inclusos)

4. Clique em Deploy

5. Aguarde ~2 minutos ate todos os servicos ficarem Active

3. Gerar dominio publico

1. Clique no servico Evolution API

2. Va em Settings → Networking → Generate Domain

3. Anote a URL gerada (ex: evolution-api-production-xxxx.up.railway.app)

4. Configurar API Key

No servico Evolution API, va em Variables e adicione:

Clique em Deploy para aplicar.

5. Criar instancia e escanear QR

# Criar instancia
curl -X POST "https://SUA-URL.up.railway.app/instance/create" \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"meuwhats","integration":"WHATSAPP-BAILEYS","qrcode":true}'

# Pegar QR code (rode e escaneie com o WhatsApp)
curl "https://SUA-URL.up.railway.app/instance/connect/meuwhats" \
  -H "apikey: SUA_API_KEY"

O campo base64 da resposta e a imagem do QR. Salve e abra:

# Salvar QR como imagem e abrir
curl "https://SUA-URL.up.railway.app/instance/connect/meuwhats" \
  -H "apikey: SUA_API_KEY" | python3 -c "
import json,sys,base64
d=json.load(sys.stdin)
b64=d['base64'].replace('data:image/png;base64,','')
open('qr.png','wb').write(base64.b64decode(b64))
print('QR salvo em qr.png')
"
open qr.png   # macOS
# start qr.png  # Windows

Escaneie com seu WhatsApp: Configuracoes > Aparelhos conectados > Conectar dispositivo

6. Instalar o MCP server

git clone https://github.com/SEU_USUARIO/mcp-zap.git
cd mcp-zap
uv venv
uv pip install -e .

7. Registrar no Claude Code

Edite ~/.claude.json e adicione dentro de mcpServers:

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "https://SUA-URL.up.railway.app",
        "EVOLUTION_API_KEY": "SUA_API_KEY",
        "EVOLUTION_INSTANCE": "meuwhats"
      }
    }
  }
}

Windows: use o caminho completo do .exe: "command": "C:/Users/SEU_USUARIO/mcp-zap/.venv/Scripts/evolution-api-mcp.exe"

Reabra o Claude Code e pronto.

Opcao B — Docker local

Para quem prefere rodar tudo na propria maquina.

Pre-requisitos

• Docker Desktop

• Python 3.11+

• uv

• Claude Code

1. Subir a Evolution API

git clone https://github.com/SEU_USUARIO/mcp-zap.git
cd mcp-zap
docker compose up -d

Aguarde ~15 segundos e teste:

curl http://localhost:8080/
# {"status":200,"message":"Welcome to the Evolution API, it is working!"}

2. Conectar seu WhatsApp

1. Acesse http://localhost:8080/manager/

2. Use a API Key: evo_mcp_2024

3. Crie uma instancia (ex: meuwhats)

4. Clique em Gerar QR Code e escaneie

3. Instalar e registrar o MCP

uv venv
uv pip install -e .

Edite ~/.claude.json:

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "evo_mcp_2024",
        "EVOLUTION_INSTANCE": "meuwhats"
      }
    }
  }
}

Windows: use o caminho completo: C:/Users/SEU_USUARIO/mcp-zap/.venv/Scripts/evolution-api-mcp.exe

Usando

Apos configurar, reabra o Claude Code:

> envia uma mensagem pro 5511999999999 dizendo oi
> mostra minhas conversas recentes
> qual foi a ultima mensagem do fulano?

Configuracao

Estrutura

mcp-zap/
├── docker-compose.yml          # Evolution API + PostgreSQL (opcao local)
├── pyproject.toml              # Dependencias Python
└── src/evolution_api_mcp/
    ├── server.py               # MCP server (FastMCP + CodeMode)
    ├── client.py               # HTTP client async
    └── tools/
        ├── instance.py         # Criar/conectar/deletar instancias
        ├── messages.py         # Enviar texto, midia, audio, etc.
        └── chat.py             # Listar chats, ler mensagens

Tools disponiveis

Instance

• create_instance — Criar instancia WhatsApp

• connect_instance — Conectar e gerar QR code

• fetch_instances — Listar instancias

• connection_state — Verificar estado da conexao

• logout_instance — Desconectar WhatsApp

• restart_instance — Reiniciar instancia

• delete_instance — Deletar instancia

Messages

• send_text — Enviar texto

• send_media — Enviar imagem, video ou documento

• send_audio — Enviar audio/nota de voz

• send_location — Enviar localizacao

• send_contact — Enviar cartao de contato

• send_reaction — Reagir com emoji

• send_poll — Enviar enquete

• send_buttons — Enviar botoes interativos

• send_list — Enviar lista interativa

• send_sticker — Enviar sticker

Chat

• find_chats — Listar conversas

• find_messages — Ler mensagens de um chat

• archive_chat — Arquivar/desarquivar chat

• mark_message_as_read — Marcar como lido

Licenca

MIT