Evolution API MCP Server

MCP Server para Evolution API - Integrao completa do WhatsApp com Claude Desktop via Model Context Protocol (MCP).

Este servidor permite que o Claude Desktop interaja com o WhatsApp atravs 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
• Vdeos com legendas
• Documentos (PDF, DOCX, XLSX, etc)
• udios

Gerenciamento de Conversas

• Listar conversas ativas com nomes
• Buscar mensagens por texto
• Obter mensagens de conversa especfica
• Enriquecimento automtico com nomes de contatos

Gerenciamento de Contatos

• Listar contatos salvos
• Buscar contatos por ID
• Obter nome de contato por nmero
• Cache inteligente de nomes (5min TTL)

Performance

• Bulk fetch de contatos (1 request vs N+1)
• Cache em memria para nomes
• Enriquecimento automtico de chats

Qualidade

• Validao de nmeros 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. Instncia 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 instncia (instance name)

---

Quick Start com Docker (Recomendado!)

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

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

Documentao completa: docker/README.md

---

Instalao Local (Modo MCP Stdio)

1. Clone o Repositrio

git clone https://github.com/PabloBispo/evoapi-mcp.git
cd evoapi-mcp

2. Instale as Dependncias

# Usando uv (recomendado)
uv sync

# OU usando pip
pip install -e .

3. Configure as Variveis de Ambiente

Crie um arquivo .env na raiz do projeto:

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

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 configurao do Claude Desktop:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Adicione o servidor MCP:

{
  "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 diretrio 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 nmero 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 nmero 5511999999999

Busque mensagens que contenham a palavra "reunio"

Gerenciar Contatos

Liste os primeiros 20 contatos do meu WhatsApp

Qual  o nome do contato 5511987654321?

Mostre informaes do contato 5511999999999

Status da Conexo

Verifique o status da conexo do WhatsApp

Mostre informaes da instncia

---

Tools Disponveis

Envio de Mensagens

Tool	Descrio	Parmetros
send_text_message	Envia mensagem de texto	number, text, link_preview
send_image	Envia imagem	number, image_url, caption
send_video	Envia vdeo	number, video_url, caption
send_document	Envia documento	number, document_url, filename, caption
send_audio	Envia udio	number, audio_url

Conversas e Mensagens

Tool	Descrio	Parmetros
list_chats	Lista conversas ativas	limit
get_chat_messages	Obtm mensagens de conversa	number, limit
find_messages	Busca mensagens por termo	query, chat_id, limit

Contatos

Tool	Descrio	Parmetros
get_contacts	Lista contatos salvos	limit
find_contact	Busca contato especfico	contact_id, limit
get_contact_name_by_number	Obtm nome por nmero	number

Status e Presena

Tool	Descrio	Parmetros
get_connection_status	Verifica status da conexo	-
get_instance_info	Informaes da instncia	-
set_presence	Define status de presena	status, number

---

Modos de Uso

Este projeto suporta dois modos de operao:

1. Modo Stdio (Claude Desktop)

• Comunicao via stdio (stdin/stdout)
• Integrao nativa com Claude Desktop
• Melhor para uso pessoal local
• Configurao 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 produo e equipes
• Swagger docs em /docs

Voc pode usar ambos simultaneamente!

---

Troubleshooting

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

Soluo:

• Verifique se o caminho no claude_desktop_config.json absoluto (no relativo)
• Use pwd para obter o caminho completo: cd evoapi-mcp && pwd

Erro: "HTTP 401: Unauthorized"

Soluo:

• Verifique se o EVOLUTION_API_TOKEN est correto
• Confirme que o token tem permisses necessrias

Erro: "HTTP 404: Endpoint no encontrado"

Soluo:

• 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 no aparecem

Soluo:

• Reinicie o Claude Desktop para limpar o cache
• Verifique se os contatos esto salvos no WhatsApp
• Cache expira automaticamente aps 5 minutos

Listagem de conversas muito lenta

Soluo:

• J otimizado! Usa bulk fetch de contatos (2 requests ao invs de N+1)
• Se ainda estiver lento, verifique a conexo com a Evolution API

Como Ver os Logs

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

macOS/Linux:

# Logs do Claude Desktop
tail -f ~/Library/Logs/Claude/mcp*.log

Ou rode manualmente para debug:

cd evoapi-mcp
uv run evoapi-mcp
# Depois teste chamando tools via stdin

---

Roadmap

Veja o arquivo ROADMAP.md para planos futuros:

FASE 1 - Correes Crticas (Curto Prazo)

• Unificar duplicaes de cdigo
• Adicionar validaes robustas
• Cache com TTL

FASE 2 - Melhorias de Qualidade (Mdio Prazo)

• Type safety com Pydantic
• Retry logic automtico
• Sanitizao de logs

FASE 3 - Novas Funcionalidades (Longo Prazo)

• Gerenciamento de grupos
• Deletar/editar mensagens
• Upload de arquivos locais
• Download de mdias recebidas
• Status (stories)

FASE 4 - DevOps

• Testes automatizados
• CI/CD com GitHub Actions
• Documentao completa

---

Documentao Adicional

• ROADMAP.md - Plano de desenvolvimento futuro
• TODO.md - Tarefas pendentes organizadas
• KNOWN_ISSUES.md - Problemas conhecidos e solues
• FIXES.md - Histrico de correes aplicadas

---

Contribuindo

Contribuies so bem-vindas!

Como Contribuir

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/amazing-feature)
3. Commit suas mudanas (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 documentao
• Siga o estilo de cdigo existente
• Use commits semnticos

---

Licena

Este projeto est sob a licena MIT. Veja o arquivo LICENSE para mais detalhes.

---

Agradecimentos

• Evolution API - API de WhatsApp incrvel
• Model Context Protocol - Protocolo MCP
• Anthropic - Claude Desktop
• FastMCP - Framework Python para MCP

---

Suporte

• Issues: GitHub Issues
• Discusses: GitHub Discussions

---

Star History

Se este projeto foi til, considere dar uma estrela!

---

Feito com usando Claude Code