Evolution API MCP

Servidor MCP para enviar y recibir mensajes en WhatsApp directamente desde Claude Code, usando Evolution API (código abierto, autohospedado).

Qué hace

• Crear y gestionar instancias de WhatsApp

• Enviar mensajes de texto, multimedia, audio, ubicación, contactos, encuestas, stickers, botones y listas

• Leer conversaciones y mensajes recibidos

• Reaccionar a mensajes, archivar chats, marcar como leído

Related MCP server: mcp-evolution

Requisitos previos

• Docker Desktop

• Python 3.11+

• uv (gestor de paquetes de Python)

• Claude Code

Instalación

1. Levantar la Evolution API

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

Espere unos 15 segundos y pruebe:

curl http://localhost:8080/

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

2. Instalar el servidor MCP

uv venv
uv pip install -e .

3. Registrar en Claude Code

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

O añádalo manualmente en el archivo ~/.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: el comando puede necesitar la ruta completa del .exe: C:/Users/SU_USUARIO/evolution-api-mcp/.venv/Scripts/evolution-api-mcp.exe

4. Conectar su WhatsApp

1. Abra http://localhost:8080/manager/ en el navegador

2. Use la Global API Key: evo_mcp_2024

3. Cree una instancia (ej: "miwhats")

4. Haga clic en "Generar QR Code"

5. Escanee con su WhatsApp: Configuración > Dispositivos vinculados > Conectar un dispositivo

5. ¡Usar!

Reabra Claude Code y comience a usar:

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

Configuración

La API key predeterminada de Docker Compose es evo_mcp_2024. Cámbiela en el docker-compose.yml si lo desea.

Estructura

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

Herramientas disponibles

Instance

• create_instance - Crear instancia de WhatsApp

• connect_instance - Conectar y generar código QR

• fetch_instances - Listar instancias

• connection_state - Verificar estado de la conexión

• logout_instance - Desconectar WhatsApp

• restart_instance - Reiniciar instancia

• delete_instance - Eliminar instancia

Messages

• send_text - Enviar texto

• send_media - Enviar imagen, video o documento

• send_audio - Enviar audio/nota de voz

• send_location - Enviar ubicación

• send_contact - Enviar tarjeta de contacto

• send_reaction - Reaccionar con emoji

• send_poll - Enviar encuesta

• send_buttons - Enviar botones interactivos

• send_list - Enviar lista interactiva

• send_sticker - Enviar sticker

Chat

• find_chats - Listar conversaciones

• find_messages - Leer mensajes de un chat

• archive_chat - Archivar/desarchivar chat

• mark_message_as_read - Marcar como leído

Licencia

MIT