🚀 Evolution API MCP Server

MCP Server para Evolution API - Integração completa do WhatsApp com Claude Desktop via Model Context Protocol (MCP).

Este servidor permite que o Claude Desktop interaja com o WhatsApp através da Evolution API, possibilitando envio de mensagens, gerenciamento de conversas, busca de contatos e muito mais.

✨ Features

📤 Envio de Mensagens

• ✅ Mensagens de texto com preview de links

• ✅ Imagens com legendas

• ✅ Vídeos com legendas

• ✅ Documentos (PDF, DOCX, XLSX, etc)

• ✅ Áudios

💬 Gerenciamento de Conversas

• ✅ Listar conversas ativas com nomes

• ✅ Buscar mensagens por texto

• ✅ Obter mensagens de conversa específica

• ✅ Enriquecimento automático com nomes de contatos

👥 Gerenciamento de Contatos

• ✅ Listar contatos salvos

• ✅ Buscar contatos por ID

• ✅ Obter nome de contato por número

• ✅ Cache inteligente de nomes (5min TTL)

⚡ Performance

• ✅ Bulk fetch de contatos (1 request vs N+1)

• ✅ Cache em memória para nomes

• ✅ Enriquecimento automático de chats

🛡️ Qualidade

• ✅ Validação de números de telefone

• ✅ Type hints completos

• ✅ Error handling robusto

• ✅ Logs estruturados

📋 Pré-requisitos

1. Python 3.10+ (para uso local)

2. Claude Desktop instalado (para modo MCP stdio)

3. Docker & Docker Compose (para deploy completo)

4. Instância Evolution API rodando (ou use nosso Docker Compose)

   • Você precisa de:

     • URL base da API (ex: https://api.example.com)

     • API Token (apikey)

     • Nome da instância (instance name)

🐳 Quick Start com Docker (Recomendado!)

Deploy completo Evolution API + MCP HTTP Server em 3 comandos:

Resultado:

• ✅ PostgreSQL rodando

• ✅ Redis rodando

• ✅ Evolution API em http://localhost:8080

• ✅ MCP HTTP Server em http://localhost:3000

• ✅ Swagger UI em http://localhost:3000/docs

Documentação completa: docker/README.md

🔧 Instalação Local (Modo MCP Stdio)

1. Clone o Repositório

2. Instale as Dependências

3. Configure as Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

Exemplo real:

4. Configure o Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

macOS:

Windows:

Adicione o servidor MCP:

⚠️ IMPORTANTE: Use o caminho absoluto completo para o diretório do projeto!

5. Reinicie o Claude Desktop

Feche completamente (⌘Q no macOS) e reabra o Claude Desktop.

🎯 Como Usar

Exemplos de Comandos no Claude Desktop

📤 Enviar Mensagens

💬 Consultar Conversas

👥 Gerenciar Contatos

ℹ️ Status da Conexão

🛠️ Tools Disponíveis

Envio de Mensagens

Conversas e Mensagens

Contatos

Status e Presença

🌐 Modos de Uso

Este projeto suporta dois modos de operação:

1. Modo Stdio (Claude Desktop)

• Comunicação via stdio (stdin/stdout)

• Integração nativa com Claude Desktop

• Melhor para uso pessoal local

• Configuração em claude_desktop_config.json

2. Modo HTTP (Docker/Servidor)

• API REST com Swagger UI

• Deploy em containers Docker

• Acesso remoto via HTTP

• Ideal para produção e equipes

• Swagger docs em /docs

Você pode usar ambos simultaneamente! 🎉

🔍 Troubleshooting

❌ Erro: "ModuleNotFoundError: No module named 'evoapi_mcp'"

Solução:

• Verifique se o caminho no claude_desktop_config.json é absoluto (não relativo)

• Use pwd para obter o caminho completo: cd evoapi-mcp && pwd

❌ Erro: "HTTP 401: Unauthorized"

Solução:

• Verifique se o EVOLUTION_API_TOKEN está correto

• Confirme que o token tem permissões necessárias

❌ Erro: "HTTP 404: Endpoint não encontrado"

Solução:

• Verifique se o EVOLUTION_BASE_URL está correto

• Confirme se a Evolution API está rodando

• Teste manualmente: curl https://your-api.com/instance/connectionState/instance-name -H "apikey: your-token"

❌ Os nomes dos contatos não aparecem

Solução:

• Reinicie o Claude Desktop para limpar o cache

• Verifique se os contatos estão salvos no WhatsApp

• Cache expira automaticamente após 5 minutos

❌ Listagem de conversas muito lenta

Solução:

• Já otimizado! Usa bulk fetch de contatos (2 requests ao invés de N+1)

• Se ainda estiver lento, verifique a conexão com a Evolution API

🔍 Como Ver os Logs

Os logs aparecem no stderr do processo MCP. Para vê-los:

macOS/Linux:

Ou rode manualmente para debug:

🗺️ Roadmap

Veja o arquivo ROADMAP.md para planos futuros:

🔴 FASE 1 - Correções Críticas (Curto Prazo)

• Unificar duplicações de código

• Adicionar validações robustas

• Cache com TTL

🟡 FASE 2 - Melhorias de Qualidade (Médio Prazo)

• Type safety com Pydantic

• Retry logic automático

• Sanitização de logs

🟢 FASE 3 - Novas Funcionalidades (Longo Prazo)

• Gerenciamento de grupos

• Deletar/editar mensagens

• Upload de arquivos locais

• Download de mídias recebidas

• Status (stories)

🧪 FASE 4 - DevOps

• Testes automatizados

• CI/CD com GitHub Actions

• Documentação completa

📚 Documentação Adicional

• ROADMAP.md - Plano de desenvolvimento futuro

• TODO.md - Tarefas pendentes organizadas

• KNOWN_ISSUES.md - Problemas conhecidos e soluções

• FIXES.md - Histórico de correções aplicadas

🤝 Contribuindo

Contribuições são bem-vindas! 🎉

Como Contribuir

1. Fork o projeto

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

3. Commit suas mudanças (git commit -m 'Add amazing feature')

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

5. Abra um Pull Request

Diretrizes

• Adicione testes para novas funcionalidades

• Atualize a documentação

• Siga o estilo de código existente

• Use commits semânticos

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

• Evolution API - API de WhatsApp incrível

• Model Context Protocol - Protocolo MCP

• Anthropic - Claude Desktop

• FastMCP - Framework Python para MCP

📞 Suporte

• 🐛 Issues: GitHub Issues

• 💬 Discussões: GitHub Discussions

⭐ Star History

Se este projeto foi útil, considere dar uma estrela! ⭐

Feito com ❤️ usando Claude Code