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

No Railway, clique em New Project
Clique em Deploy a template
Pesquise Evolution API (o template com mais de 2000 projetos — tem Postgres + Redis inclusos)
Clique em Deploy
Aguarde ~2 minutos ate todos os servicos ficarem Active

3. Gerar dominio publico

Clique no servico Evolution API
Va em Settings → Networking → Generate Domain
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:

Variavel	Valor
`AUTHENTICATION_TYPE`	`apikey`
`AUTHENTICATION_API_KEY`	Uma chave forte (ex: gere com `openssl rand -hex 16`)

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

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

Acesse http://localhost:8080/manager/
Use a API Key: evo_mcp_2024
Crie uma instancia (ex: meuwhats)
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

Variavel	Descricao	Exemplo
`EVOLUTION_API_URL`	URL da Evolution API	`https://xxxx.up.railway.app` ou `http://localhost:8080`
`EVOLUTION_API_KEY`	API key de autenticacao	`96CF28F9329F-44A3-80DB-5190D7B27185`
`EVOLUTION_INSTANCE`	Nome da instancia criada	`meuwhats`

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

Evolution API MCP