Evolution API MCP Server

MCP Server para integração com Evolution API, permitindo envio e gerenciamento de mensagens WhatsApp através do Claude.

Características

• ✅ Envio de mensagens de texto

• ✅ Envio de mídia (imagens, vídeos, documentos, áudios)

• ✅ Envio de localização e contatos

• ✅ Listagem de chats e mensagens

• ✅ Consulta de mensagens não lidas

• ✅ Gerenciamento de presença (online/offline)

• ✅ Validação automática de números de telefone

• ✅ Tratamento robusto de erros

• ✅ Logging detalhado

Pré-requisitos

• Python 3.10 ou superior

• uv (gerenciador de pacotes Python)

• Servidor Evolution API configurado e rodando

• Token de autenticação da Evolution API

• Uma instância WhatsApp criada e conectada

Instalação

1. Clone ou baixe o projeto

2. Configure as variáveis de ambiente

Copie o arquivo de exemplo e edite com suas credenciais:

Edite o arquivo .env:

Importante:

• EVOLUTION_BASE_URL: URL do seu servidor Evolution API

• EVOLUTION_API_TOKEN: Token de autenticação (API Key)

• EVOLUTION_INSTANCE_NAME: Nome da instância WhatsApp (deve estar criada e conectada)

3. Instale as dependências

4. Teste localmente (opcional)

Antes de instalar no Claude Desktop, você pode testar o servidor:

Isso abrirá uma interface web onde você pode testar os tools disponíveis.

5. Instale no Claude Desktop

Ou configure manualmente editando ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%/Claude/claude_desktop_config.json (Windows):

Nota: Substitua /caminho/completo/para/evoapi-mcp pelo caminho absoluto do projeto.

6. Reinicie o Claude Desktop

Após a instalação, reinicie o Claude Desktop para carregar o servidor MCP.

Uso

Enviando mensagens de texto

Enviando imagens

Enviando documentos

Consultando mensagens não lidas

Listando conversas

Obtendo mensagens de uma conversa

Alterando presença

ou

Tools Disponíveis

Envio de Mensagens

• send_text_message - Envia mensagem de texto

• send_image - Envia imagem

• send_document - Envia documento (PDF, DOCX, XLSX, etc.)

• send_video - Envia vídeo

• send_audio - Envia áudio

• send_location - Envia localização geográfica

• send_contact - Envia contato

Gerenciamento de Chats

• list_chats - Lista conversas ativas

• get_chat_messages - Obtém mensagens de uma conversa

• get_chat_by_number - Obtém chat_id a partir de um número

• get_unread_messages - Lista mensagens não lidas

• mark_chat_as_read - Marca chat como lido

Status e Presença

• get_connection_status - Verifica status da conexão

• set_presence - Define presença (available/unavailable/composing/recording)

• get_instance_info - Obtém informações da instância

Formato de Números

Todos os números devem estar no formato internacional sem o sinal de '+':

✅ Correto: 5511999999999 (Brasil) ✅ Correto: 1234567890 (EUA) ❌ Errado: +5511999999999 ❌ Errado: (11) 99999-9999

O servidor normaliza automaticamente os números removendo caracteres não numéricos.

Troubleshooting

Erro: "Instância desconectada"

A instância WhatsApp perdeu a conexão. Soluções:

1. Verifique se o servidor Evolution API está rodando

2. Reconecte a instância via interface web da Evolution API

3. Use get_connection_status() para verificar o estado

Erro: "Falha de autenticação"

Token de API inválido. Verifique:

1. O token no .env está correto

2. O token não expirou

3. O servidor Evolution API está acessível

Erro: "Número inválido"

O número de telefone não está no formato correto. Use formato internacional sem '+':

• Brasil: 5511999999999

• EUA: 1234567890

Erro: "Timeout"

Operação demorou muito. Possíveis causas:

1. Servidor Evolution API lento ou sobrecarregado

2. Conexão de rede instável

3. Arquivo de mídia muito grande

Solução: Aumente o timeout no .env:

Logs do servidor

Os logs do servidor MCP são enviados para stderr. Para visualizar:

• macOS/Linux: Verifique o Console do sistema ou logs do Claude Desktop

• Windows: Verifique o Visualizador de Eventos

Desenvolvimento

Estrutura do projeto

Executando testes

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do projeto

2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)

3. Commit suas mudanças

4. Push para a branch (git push origin feature/nova-funcionalidade)

5. Abra um Pull Request

Notas Importantes

TODOs

Alguns métodos da Evolution API precisam ser verificados/ajustados conforme a API exata da biblioteca evolutionapi:

• send_location() - Verificar parâmetros corretos

• send_contact() - Verificar formato de contato

• list_chats() - Verificar estrutura de retorno

• get_chat_messages() - Verificar paginação

• get_unread_messages() - Verificar formato de retorno

• set_presence() - Verificar valores válidos de status

Consulte a documentação da Evolution API para detalhes específicos.

Segurança

• Nunca commite o arquivo .env com suas credenciais

• Nunca exponha seu token de API publicamente

• Use HTTPS para o EVOLUTION_BASE_URL em produção

• Mantenha seu servidor Evolution API protegido por firewall

Recursos

• Evolution API - Site oficial

• Documentação Evolution API

• Cliente Python Evolution API

• Model Context Protocol

• MCP Python SDK

Licença

Este projeto é fornecido "como está", sem garantias. Use por sua conta e risco.

Suporte

Para problemas ou dúvidas:

1. Verifique a seção Troubleshooting

2. Consulte a documentação da Evolution API

3. Abra uma issue no repositório do projeto

Desenvolvido para uso com Claude Desktop e Evolution API.