Evolution MCP Server

Servidor MCP (Model Context Protocol) para integração com Evolution API WhatsApp.

📋 Descrição

Este servidor expõe ferramentas MCP para gerenciar instâncias WhatsApp e enviar mensagens através da Evolution API.

🚀 Funcionalidades

O servidor oferece as seguintes ferramentas MCP:

1. create_instance

Cria uma nova instância WhatsApp.

Parâmetros:

instanceName (obrigatório): Nome único da instância
qrcode (opcional): Gerar QR Code (padrão: true)
integration (opcional): Tipo de integração (padrão: "WHATSAPP-BAILEYS")

Exemplo: ``json { "instanceName": "minha_instancia", "qrcode": true, "integration": "WHATSAPP-BAILEYS" } ``

2. delete_instance

Deleta uma instância existente.

Parâmetros:

instanceName (obrigatório): Nome da instância a ser deletada

Exemplo: ``json { "instanceName": "minha_instancia" } ``

3. check_whatsapp_numbers

Verifica quais números são válidos no WhatsApp.

Parâmetros:

instanceName (obrigatório): Nome da instância
numbers (obrigatório): Lista de números para verificar

Exemplo: ``json { "instanceName": "minha_instancia", "numbers": ["5511999999999", "5511888888888"] } ``

4. send_text

Envia uma mensagem de texto.

Parâmetros:

instanceName (obrigatório): Nome da instância
number (obrigatório): Número do destinatário
text (obrigatório): Texto da mensagem

Exemplo: ``json { "instanceName": "minha_instancia", "number": "5511999999999", "text": "Olá! Esta é uma mensagem de teste." } ``

5. send_media

Envia mídia (imagem/vídeo/documento/áudio).

Parâmetros:

instanceName (obrigatório): Nome da instância
number (obrigatório): Número do destinatário
mediatype (obrigatório): Tipo de mídia (image, video, document, audio)
media (obrigatório): URL da mídia ou base64
mimetype (obrigatório): MIME type (ex: image/png, video/mp4)
caption (opcional): Legenda da mídia
fileName (opcional): Nome do arquivo

Exemplo: ``json { "instanceName": "minha_instancia", "number": "5511999999999", "mediatype": "image", "media": "https://exemplo.com/imagem.png", "mimetype": "image/png", "caption": "Confira esta imagem!", "fileName": "imagem.png" } ``

6. fetch_profile

Busca informações do perfil de um contato.

Parâmetros:

instanceName (obrigatório): Nome da instância
number (obrigatório): Número do contato

Exemplo: ``json { "instanceName": "minha_instancia", "number": "5511999999999" } ``

7. connection_state

Verifica o estado da conexão da instância.

Parâmetros:

instanceName (obrigatório): Nome da instância

Exemplo: ``json { "instanceName": "minha_instancia" } ``

8. logout_instance

Faz logout/desconecta uma instância WhatsApp.

Parâmetros:

instanceName (obrigatório): Nome da instância para desconectar

Exemplo: ``json { "instanceName": "minha_instancia" } ``

🛠️ Requisitos

Python 3.11.11
Docker e Docker Compose
Evolution API em execução
Claude Desktop (para usar o servidor MCP)

📦 Instalação

Com Docker Compose (Recomendado)

Clone o repositório:

git clone <repo-url>
cd evolution_mcp

Copie o arquivo de exemplo de variáveis de ambiente:

copy .env.example .env

Edite o arquivo .env e configure suas credenciais:

EVOLUTION_API_KEY=sua_api_key_aqui
EVOLUTION_BASE_URL=http://evolution-api:8080
LOG_LEVEL=INFO

Construa e inicie o container:

docker-compose up -d --build

Configure o Claude Desktop editando o arquivo:

%APPDATA%\Claude\claude_desktop_config.json

Adicione: ``json { "mcpServers": { "evolution-api": { "command": "docker", "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"] } } } ``

Reinicie o Claude Desktop

Desenvolvimento Local com Conda

Crie o ambiente conda:

conda create -n evolution_mcp python=3.11.11
conda activate evolution_mcp

Instale as dependências:

pip install -r requirements.txt

Configure as variáveis de ambiente:

set EVOLUTION_API_KEY=sua_api_key_aqui
set EVOLUTION_BASE_URL=http://localhost:8080
set LOG_LEVEL=DEBUG

Execute o servidor:

python -m mcp_server

🔧 Configuração

Variáveis de Ambiente

| Variável | Descrição | Padrão | |----------|-----------|--------| | EVOLUTION_API_KEY | API Key da Evolution API | (obrigatório) | | EVOLUTION_BASE_URL | URL base da Evolution API | http://evolution-api:8080 | | LOG_LEVEL | Nível de log (DEBUG, INFO, WARNING, ERROR) | INFO |

Portas

5020: Porta do servidor MCP

🐳 Docker

Dockerfile

O projeto inclui um Dockerfile otimizado para Python 3.11.11.

Docker Compose

O docker-compose.yml está configurado com:

Rede isolada (evolution-network)
Volume para desenvolvimento em tempo real (./src:/app/src)
Reinício automático (restart: unless-stopped)
Variáveis de ambiente configuráveis

📝 Estrutura do Projeto

evolution_mcp/
├── mcp_server.py          # Servidor MCP principal
├── Dockerfile             # Imagem Docker
├── docker-compose.yml     # Orquestração Docker
├── requirements.txt       # Dependências Python
├── .env.example          # Exemplo de variáveis de ambiente
├── SECURITY.md           # Guia de segurança
└── README.md             # Esta documentação

🔍 Logs e Debug

Para ativar logs detalhados:

set LOG_LEVEL=DEBUG

Ou no .env: ``env LOG_LEVEL=DEBUG ``

🤝 Integração com Evolution API

O servidor se comunica com a Evolution API através de requisições HTTP, incluindo automaticamente o header apikey em todas as requisições.

Endpoints da Evolution API Utilizados

POST /instance/create - Criar instância
DELETE /instance/delete/{instanceName} - Deletar instância
POST /chat/whatsappNumbers/{instanceName} - Verificar números
POST /message/sendText/{instanceName} - Enviar texto
POST /message/sendMedia/{instanceName} - Enviar mídia
GET /chat/fetchProfile/{instanceName} - Buscar perfil

🔌 Integração com Claude Desktop

O servidor MCP foi projetado para ser usado com o Claude Desktop via Docker:

O container fica rodando em modo daemon (não executa o servidor automaticamente)
O Claude Desktop conecta via docker exec -i quando precisa usar as ferramentas
A comunicação acontece via STDIO (stdin/stdout)

Configuração do Claude Desktop

Edite: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"]
    }
  }
}

Importante: O container precisa estar rodando antes de usar as ferramentas no Claude Desktop.

🚨 Tratamento de Erros

O servidor trata os seguintes tipos de erros:

Erros HTTP: Retorna status code e mensagem da Evolution API
Erros de validação: Valida parâmetros antes de enviar
Erros de conexão: Timeout de 30 segundos por requisição
Erros desconhecidos: Logs detalhados para debug

📄 Licença

Este projeto é fornecido como está, sem garantias.

🆘 Suporte

Para problemas com:

Evolution API: Consulte a documentação oficial da Evolution API
MCP: Consulte a documentação do Model Context Protocol
Este servidor: Abra uma issue no repositório

🔄 Atualizações

Para atualizar o servidor:

docker-compose down
docker-compose pull
docker-compose up -d

🐛 Troubleshooting

Container em loop de restart

Se o container ficar reiniciando continuamente: ```bash

Pare o container

docker-compose down

Reconstrua com as mudanças

docker-compose up -d --build

Verifique que o container está rodando

docker ps | findstr evolution-mcp ```

Claude Desktop não encontra as ferramentas

Verifique se o container está rodando: docker ps
Teste a conexão manualmente:

docker exec -i evolution-mcp python -m mcp_server

Reinicie o Claude Desktop completamente
Verifique os logs do Claude Desktop em:

%APPDATA%\Claude\logs\mcp-server-evolution-api.log

Erro de API Key

Se receber erros de autenticação:

Verifique o arquivo .env
Recrie o container:

docker-compose down
docker-compose up -d

Teste manual das ferramentas

Para testar se o servidor está funcionando: ``bash docker exec -it evolution-mcp python -c "from mcp_server import evolution_client; print(evolution_client.base_url)" ``

🔒 Segurança

Níveis de Proteção

O servidor MCP tem múltiplas camadas de segurança:

STDIO (não HTTP): Servidor usa stdin/stdout, não expõe porta HTTP pública
Docker Isolation: Requer acesso ao Docker para executar docker exec
Evolution API Key: Toda comunicação requer chave válida
Token MCP (Opcional): Autenticação adicional ao servidor MCP
Audit Logging: Registra todas as operações

Configuração de Segurança Recomendada

Para ambientes de produção (VPS):

# 1. Gerar token de segurança
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 2. Adicionar ao .env
echo "MCP_SERVER_TOKEN=seu_token_aqui" >> .env

# 3. Habilitar logs de auditoria
echo "ENABLE_AUDIT_LOG=true" >> .env

Importante: Em VPS, configure também:

Firewall (UFW/iptables)
SSH com chaves (sem senha)
Acesso limitado ao Docker daemon

📖 Guia completo: Veja SECURITY.md para detalhes completos

⚠️ Notas Importantes

Certifique-se de que a Evolution API está acessível na URL configurada
Use números no formato internacional sem '+' (ex: 5511999999999)
Para desenvolvimento, use volumes montados para hot-reload
Em produção (VPS), configure MCP_SERVER_TOKEN e firewall
Mantenha suas chaves seguras e não commite no Git
O container precisa estar rodando para o Claude Desktop conectar
Após editar claude_desktop_config.json, sempre reinicie o Claude Desktop
Monitore logs de auditoria regularmente: docker-compose logs -f | findstr AUDIT

Evolution MCP Server