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.

Related MCP server: mcp-zap

🚀 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

1. Clone o repositório:

git clone <repo-url>
cd evolution_mcp

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

copy .env.example .env

3. 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

4. Construa e inicie o container:

docker-compose up -d --build

5. Configure o Claude Desktop editando o arquivo: %APPDATA%\Claude\claude_desktop_config.json

Adicione:

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

6. Reinicie o Claude Desktop

Desenvolvimento Local com Conda

1. Crie o ambiente conda:

conda create -n evolution_mcp python=3.11.11
conda activate evolution_mcp

2. Instale as dependências:

pip install -r requirements.txt

3. 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

4. Execute o servidor:

python -m mcp_server

🔧 Configuração

Variáveis de Ambiente

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:

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:

1. O container fica rodando em modo daemon (não executa o servidor automaticamente)

2. O Claude Desktop conecta via docker exec -i quando precisa usar as ferramentas

3. 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:

# 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

1. Verifique se o container está rodando: docker ps

2. Teste a conexão manualmente:

docker exec -i evolution-mcp python -m mcp_server

3. Reinicie o Claude Desktop completamente

4. 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:

1. Verifique o arquivo .env

2. Recrie o container:

docker-compose down
docker-compose up -d

Teste manual das ferramentas

Para testar se o servidor está funcionando:

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:

1. STDIO (não HTTP): Servidor usa stdin/stdout, não expõe porta HTTP pública

2. Docker Isolation: Requer acesso ao Docker para executar docker exec

3. Evolution API Key: Toda comunicação requer chave válida

4. Token MCP (Opcional): Autenticação adicional ao servidor MCP

5. 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

1. Certifique-se de que a Evolution API está acessível na URL configurada

2. Use números no formato internacional sem '+' (ex: 5511999999999)

3. Para desenvolvimento, use volumes montados para hot-reload

4. Em produção (VPS), configure MCP_SERVER_TOKEN e firewall

5. Mantenha suas chaves seguras e não commite no Git

6. O container precisa estar rodando para o Claude Desktop conectar

7. Após editar claude_desktop_config.json, sempre reinicie o Claude Desktop

8. Monitore logs de auditoria regularmente: docker-compose logs -f | findstr AUDIT