MCP 服务器

mcp-zap

MCP server for sending and receiving WhatsApp messages through Evolution API, enabling management of instances, messages, and chats directly from Claude Code.

README

Evolution API MCP

MCP server para enviar e receber mensagens no WhatsApp direto do Claude Code, usando Evolution API (open-source, self-hosted).

O que faz

Criar e gerenciar instancias WhatsApp
Enviar mensagens de texto, midia, audio, localizacao, contatos, enquetes, stickers, botoes e listas
Ler conversas e mensagens recebidas
Reagir a mensagens, arquivar chats, marcar como lido

Pre-requisitos

Docker Desktop
Python 3.11+
uv (gerenciador de pacotes Python)
Claude Code

Instalacao

1. Subir a Evolution API

git clone https://github.com/SEU_USUARIO/evolution-api-mcp.git
cd evolution-api-mcp
docker compose up -d

Aguarde uns 15 segundos e teste:

curl http://localhost:8080/

Deve retornar {"status":200,"message":"Welcome to the Evolution API, it is working!"}.

2. Instalar o MCP server

uv venv
uv pip install -e .

3. Registrar no Claude Code

claude mcp add evolution-api -s user -- evolution-api-mcp

Ou adicione manualmente no arquivo ~/.claude.json:

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "evo_mcp_2024"
      }
    }
  }
}

Windows: o command pode precisar ser o caminho completo do .exe: C:/Users/SEU_USUARIO/evolution-api-mcp/.venv/Scripts/evolution-api-mcp.exe

4. Conectar seu WhatsApp

Abra http://localhost:8080/manager/ no navegador
Use a Global API Key: evo_mcp_2024
Crie uma instancia (ex: "meuwhats")
Clique em "Gerar QR Code"
Escaneie com seu WhatsApp: Configuracoes > Aparelhos conectados > Conectar dispositivo

5. Usar!

Reabra o Claude Code e comece a usar:

> envia uma mensagem pro 5511999999999 dizendo oi
> mostra minhas conversas recentes
> envia uma foto pra fulano

Configuracao

Variavel	Descricao	Default
`EVOLUTION_API_URL`	URL da Evolution API	`http://localhost:8080`
`EVOLUTION_API_KEY`	API key de autenticacao	(vazio)

A API key padrao do Docker Compose e evo_mcp_2024. Mude no docker-compose.yml se quiser.

Estrutura

evolution-api-mcp/
├── docker-compose.yml          # Evolution API + PostgreSQL
├── pyproject.toml               # Dependencias Python
└── src/evolution_api_mcp/
    ├── server.py                # MCP server (FastMCP + CodeMode)
    ├── client.py                # HTTP client async
    └── tools/
        ├── instance.py          # Criar/conectar/deletar instancias
        ├── messages.py          # Enviar texto, midia, audio, etc.
        └── chat.py              # Listar chats, ler mensagens