README.md•10.7 kB
# 🚀 Evolution API MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
**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](https://evolution-api.com/), 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:**
```bash
cd docker/
cp .env.docker.example .env.docker
# Edite .env.docker com suas credenciais
docker-compose up -d
```
**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](docker/README.md)
---
## 🔧 Instalação Local (Modo MCP Stdio)
### 1. Clone o Repositório
```bash
git clone https://github.com/PabloBispo/evoapi-mcp.git
cd evoapi-mcp
```
### 2. Instale as Dependências
```bash
# Usando uv (recomendado)
uv sync
# OU usando pip
pip install -e .
```
### 3. Configure as Variáveis de Ambiente
Crie um arquivo `.env` na raiz do projeto:
```bash
# Evolution API Configuration
EVOLUTION_BASE_URL=https://your-evolution-api.com
EVOLUTION_API_TOKEN=your-api-token-here
EVOLUTION_INSTANCE_NAME=your-instance-name
# Optional: Timeout (default: 30 seconds)
EVOLUTION_TIMEOUT=30
```
**Exemplo real:**
```bash
EVOLUTION_BASE_URL=https://pevo.ntropy.com.br
EVOLUTION_API_TOKEN=9795FDFBB464-495E-A823-28573A5D39EE
EVOLUTION_INSTANCE_NAME=personal_pablo_bispo_wpp
EVOLUTION_TIMEOUT=15
```
### 4. Configure o Claude Desktop
Edite o arquivo de configuração do Claude Desktop:
**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```
Adicione o servidor MCP:
```json
{
"mcpServers": {
"evolution-api": {
"command": "uv",
"args": [
"--directory",
"/caminho/completo/para/evoapi-mcp",
"run",
"evoapi-mcp"
],
"env": {
"EVOLUTION_BASE_URL": "https://your-evolution-api.com",
"EVOLUTION_API_TOKEN": "your-api-token-here",
"EVOLUTION_INSTANCE_NAME": "your-instance-name"
}
}
}
}
```
**⚠️ 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
```
Envie uma mensagem "Olá! Tudo bem?" para o número 5511999999999
```
```
Envie a imagem https://example.com/foto.jpg com legenda "Confira!" para 5511987654321
```
```
Envie o documento https://example.com/relatorio.pdf para 5511999999999
```
#### 💬 Consultar Conversas
```
Liste as 10 conversas mais recentes do meu WhatsApp
```
```
Mostre as últimas 50 mensagens do número 5511999999999
```
```
Busque mensagens que contenham a palavra "reunião"
```
#### 👥 Gerenciar Contatos
```
Liste os primeiros 20 contatos do meu WhatsApp
```
```
Qual é o nome do contato 5511987654321?
```
```
Mostre informações do contato 5511999999999
```
#### ℹ️ Status da Conexão
```
Verifique o status da conexão do WhatsApp
```
```
Mostre informações da instância
```
---
## 🛠️ Tools Disponíveis
### Envio de Mensagens
| Tool | Descrição | Parâmetros |
|------|-----------|------------|
| `send_text_message` | Envia mensagem de texto | `number`, `text`, `link_preview` |
| `send_image` | Envia imagem | `number`, `image_url`, `caption` |
| `send_video` | Envia vídeo | `number`, `video_url`, `caption` |
| `send_document` | Envia documento | `number`, `document_url`, `filename`, `caption` |
| `send_audio` | Envia áudio | `number`, `audio_url` |
### Conversas e Mensagens
| Tool | Descrição | Parâmetros |
|------|-----------|------------|
| `list_chats` | Lista conversas ativas | `limit` |
| `get_chat_messages` | Obtém mensagens de conversa | `number`, `limit` |
| `find_messages` | Busca mensagens por termo | `query`, `chat_id`, `limit` |
### Contatos
| Tool | Descrição | Parâmetros |
|------|-----------|------------|
| `get_contacts` | Lista contatos salvos | `limit` |
| `find_contact` | Busca contato específico | `contact_id`, `limit` |
| `get_contact_name_by_number` | Obtém nome por número | `number` |
### Status e Presença
| Tool | Descrição | Parâmetros |
|------|-----------|------------|
| `get_connection_status` | Verifica status da conexão | - |
| `get_instance_info` | Informações da instância | - |
| `set_presence` | Define status de presença | `status`, `number` |
---
## 🌐 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:**
```bash
# Logs do Claude Desktop
tail -f ~/Library/Logs/Claude/mcp*.log
```
**Ou rode manualmente para debug:**
```bash
cd evoapi-mcp
uv run evoapi-mcp
# Depois teste chamando tools via stdin
```
---
## 🗺️ Roadmap
Veja o arquivo [ROADMAP.md](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](ROADMAP.md)** - Plano de desenvolvimento futuro
- **[TODO.md](TODO.md)** - Tarefas pendentes organizadas
- **[KNOWN_ISSUES.md](KNOWN_ISSUES.md)** - Problemas conhecidos e soluções
- **[FIXES.md](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](LICENSE) para mais detalhes.
---
## 🙏 Agradecimentos
- [Evolution API](https://evolution-api.com/) - API de WhatsApp incrível
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocolo MCP
- [Anthropic](https://anthropic.com/) - Claude Desktop
- [FastMCP](https://github.com/jlowin/fastmcp) - Framework Python para MCP
---
## 📞 Suporte
- 🐛 **Issues:** [GitHub Issues](https://github.com/PabloBispo/evoapi-mcp/issues)
- 💬 **Discussões:** [GitHub Discussions](https://github.com/PabloBispo/evoapi-mcp/discussions)
---
## ⭐ Star History
Se este projeto foi útil, considere dar uma estrela! ⭐
[](https://star-history.com/#PabloBispo/evoapi-mcp&Date)
---
**Feito com ❤️ usando Claude Code**