Evolution API MCP Server

Servidor MCP (Model Context Protocol) que expone la Evolution API v2 (WhatsApp) como herramientas para clientes MCP como Claude Desktop, Claude Code o Cursor.

• 121 herramientas con cobertura completa de la API v2 (instancias, mensajes, chats, grupos, perfil, etiquetas, webhooks e integraciones).
• TypeScript sobre el SDK oficial, transporte stdio.
• Imagen Docker publicada en GHCR y ejecutable con npx (sin clonar).
• Multi-instancia: cada herramienta acepta instance; opcionalmente una instancia por defecto.
• Grupos activables vía EVOLUTION_TOOLS para no saturar el contexto del modelo.

Probado contra Evolution API 2.3.7.

Requisitos

• Una instancia de Evolution API v2 y su apikey global.
• Para npx / local: Node.js 18 o superior. Para Docker: solo Docker.

Cómo ejecutarlo

Hay tres formas, de la más simple a la más manual. Todas necesitan las mismas variables de entorno (ver Configuración).

Opción A — Docker (recomendada)

Imagen lista en GitHub Container Registry, no necesitas Node ni clonar nada:

docker run -i --rm \
  -e EVOLUTION_BASE_URL=https://your-evolution-instance.com \
  -e EVOLUTION_API_KEY=tu-apikey-global \
  -e EVOLUTION_DEFAULT_INSTANCE=myinstance \
  ghcr.io/serversmx/mcp-evolution-api:latest

El servidor habla MCP por stdio, por eso docker run usa -i (mantiene stdin abierto). No expone puertos.

ℹ️ La imagen es multi-arquitectura (linux/amd64 + linux/arm64): corre nativa en Macs Apple Silicon e Intel y en servidores Linux. Al publicarse por primera vez en GHCR el paquete queda privado; para que cualquiera pueda hacer docker pull, el mantenedor debe marcarlo público una sola vez: pestaña Packages del repo → paquete mcp-evolution-api → Package settings → Change visibility → Public. Mientras tanto, las Opciones B (npx) y C (local) no dependen de GHCR.

Construir la imagen localmente en vez de usar GHCR:

docker build -t evolution-api-mcp .
docker run -i --rm -e EVOLUTION_BASE_URL=... -e EVOLUTION_API_KEY=... evolution-api-mcp

Opción B — npx (sin clonar)

Compila y ejecuta directamente desde GitHub:

EVOLUTION_BASE_URL=https://your-evolution-instance.com \
EVOLUTION_API_KEY=tu-apikey-global \
EVOLUTION_DEFAULT_INSTANCE=myinstance \
npx -y github:serversmx/mcp-evolution-api

⚠️ La primera ejecución clona el repo, instala dependencias y compila TypeScript (prepare → tsc), así que puede tardar ~30–60 s. Algunos clientes MCP marcan el servidor como fallido si supera su timeout de arranque: si te pasa, córrelo una vez en una terminal para precargar la caché de npx y reintenta, o usa Docker (Opción A), que no compila en cada arranque.

Opción C — Local (clonar y compilar)

git clone https://github.com/serversmx/mcp-evolution-api.git
cd mcp-evolution-api
npm install        # compila a dist/ automáticamente (script "prepare")
cp .env.example .env   # edita tus credenciales
npm start

Configuración

Variables de entorno (ver .env.example):

Variable	Requerida	Descripción
EVOLUTION_BASE_URL	✅	URL base, p.ej. https://your-evolution-instance.com (sin slash final).
EVOLUTION_API_KEY	✅	apikey global (header apikey).
EVOLUTION_DEFAULT_INSTANCE	—	Instancia usada cuando una herramienta omite instance.
EVOLUTION_TOOLS	—	Allowlist de grupos separada por comas. Ver abajo.
EVOLUTION_TIMEOUT_MS	—	Timeout por petición (default 30000).

⚠️ La apikey global da control total sobre la instancia (crear/borrar instancias, enviar mensajes, leer chats). Trátala como un secreto: nunca la subas al repositorio ni la hornees en una imagen.

Grupos de herramientas

EVOLUTION_TOOLS controla qué grupos se exponen:

• Sin definir → grupos núcleo: instance, settings, message, chat, profile, label, group, webhook (64 tools).
• all → todos los grupos (121 tools).
• Lista explícita, p.ej. message,chat,group → solo esos.

Grupo	Núcleo	Herramientas
instance	✅	crear, conectar, estado, reiniciar, presencia, logout, borrar, listar
settings	✅	leer/escribir settings del instance
message	✅	texto, media, audio, sticker, ubicación, contacto, reacción, poll, lista, botones, status, ptv
chat	✅	verificar números, marcar leído/no leído, archivar, borrar, presencia, bloquear, foto, base64, buscar chats/mensajes/contactos/status, editar
profile	✅	perfil propio y de negocio, privacidad, nombre/estado/foto
label	✅	listar y asignar etiquetas
group	✅	crear, participantes, invitaciones, ajustes, ephemeral, salir
webhook	✅	configurar/leer webhook
websocket	—	configurar/leer websocket
rabbitmq	—	configurar/leer RabbitMQ
sqs	—	configurar/leer AWS SQS
chatwoot	—	configurar/leer Chatwoot
typebot	—	CRUD bots + start/sessions
openai	—	CRUD bots + credenciales + sessions
dify	—	CRUD bots + sessions
evolutionbot	—	CRUD bots + sessions
flowise	—	CRUD bots + sessions

Configuración en tu cliente MCP

Añade el servidor a tu config (claude_desktop_config.json, .cursor/mcp.json, o claude mcp add). Elige el bloque según cómo lo ejecutes.

⚠️ Claude Desktop (macOS) y el PATH. Claude Desktop se lanza desde Finder/Dock y hereda un PATH mínimo (/usr/bin:/bin:/usr/sbin:/sbin), por lo que a menudo no encuentra docker, npx ni node y falla con spawn docker ENOENT la primera vez. (Claude Code por CLI y Cursor heredan el PATH de tu shell, así que no les afecta.) Solución: usa la ruta absoluta del binario en "command", obtenida con which docker / which npx / which node (p.ej. /usr/local/bin/docker o /opt/homebrew/bin/node).

Con Docker:

{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EVOLUTION_BASE_URL",
        "-e", "EVOLUTION_API_KEY",
        "-e", "EVOLUTION_DEFAULT_INSTANCE",
        "ghcr.io/serversmx/mcp-evolution-api:latest"
      ],
      "env": {
        "EVOLUTION_BASE_URL": "https://your-evolution-instance.com",
        "EVOLUTION_API_KEY": "tu-apikey-global",
        "EVOLUTION_DEFAULT_INSTANCE": "myinstance"
      }
    }
  }
}

Los -e VAR sin valor reenvían la variable desde el bloque env, así la apikey no queda escrita en args.

Con npx:

{
  "mcpServers": {
    "evolution-api": {
      "command": "npx",
      "args": ["-y", "github:serversmx/mcp-evolution-api"],
      "env": {
        "EVOLUTION_BASE_URL": "https://your-evolution-instance.com",
        "EVOLUTION_API_KEY": "tu-apikey-global",
        "EVOLUTION_DEFAULT_INSTANCE": "myinstance"
      }
    }
  }
}

Local (compilado):

{
  "mcpServers": {
    "evolution-api": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-evolution-api/dist/index.js"],
      "env": {
        "EVOLUTION_BASE_URL": "https://your-evolution-instance.com",
        "EVOLUTION_API_KEY": "tu-apikey-global",
        "EVOLUTION_DEFAULT_INSTANCE": "myinstance"
      }
    }
  }
}

Con Claude Code por CLI (Docker):

claude mcp add evolution-api \
  --env EVOLUTION_BASE_URL=https://your-evolution-instance.com \
  --env EVOLUTION_API_KEY=tu-apikey-global \
  --env EVOLUTION_DEFAULT_INSTANCE=myinstance \
  -- docker run -i --rm \
     -e EVOLUTION_BASE_URL -e EVOLUTION_API_KEY -e EVOLUTION_DEFAULT_INSTANCE \
     ghcr.io/serversmx/mcp-evolution-api:latest

Verificación

Smoke test de solo lectura contra tu instancia (no envía mensajes ni modifica nada):

EVOLUTION_BASE_URL=https://your-evolution-instance.com \
EVOLUTION_API_KEY=tu-apikey-global \
EVOLUTION_DEFAULT_INSTANCE=myinstance \
node dist/smoke.js

Con la imagen Docker (sin compilar nada local):

docker run --rm --entrypoint node \
  -e EVOLUTION_BASE_URL=https://your-evolution-instance.com \
  -e EVOLUTION_API_KEY=tu-apikey-global \
  -e EVOLUTION_DEFAULT_INSTANCE=myinstance \
  ghcr.io/serversmx/mcp-evolution-api:latest dist/smoke.js

Salida esperada: 4/4 checks passed.

Ejemplos de uso (lenguaje natural)

Una vez conectado, puedes pedirle a Claude cosas como:

• "Verifica si el número 5215550123 está en WhatsApp."
• "Envía 'Hola 👋' al 5215550123 desde la instancia myinstance."
• "Lista todos los grupos de la instancia myinstance."
• "¿Cuál es el estado de conexión de mis instancias?"

Convenciones de las herramientas

• Nombre: evolution_<grupo>_<acción> (p.ej. evolution_message_send_text).
• Cada herramienta acepta instance (opcional si hay EVOLUTION_DEFAULT_INSTANCE).
• Los number aceptan dígitos con código de país o JID completo (5215550123 o 5215550123@s.whatsapp.net).
• Los errores del API se devuelven como resultado de error con el status y el mensaje de Evolution (la apikey nunca aparece en logs ni errores).

Estructura

src/
  index.ts            Server MCP (stdio): lista y ejecuta tools
  config.ts           Carga/valida variables de entorno
  client.ts           Cliente HTTP de Evolution (apikey, errores, timeout)
  registry.ts         Filtra grupos según EVOLUTION_TOOLS
  types.ts            Tipos ToolDef / ToolGroup
  schemas/common.ts   Fragmentos zod reutilizables
  tools/              Un archivo por controlador + integrations/
  smoke.ts            Smoke test de solo lectura
Dockerfile            Imagen multi-stage (build + runtime no-root)
.github/workflows/    CI (build) y publicación de la imagen en GHCR

Las herramientas de bots IA (typebot, openai, dify, evolutionbot, flowise) aceptan el objeto de configuración (config/settings) tal cual lo documenta Evolution API, por su gran cantidad de campos específicos.

Desarrollo

npm run watch    # compila en modo watch
npm run build    # compila a dist/
npm start        # ejecuta el servidor (requiere env)

La CI (.github/workflows/ci.yml) compila con tsc en cada push/PR. Al hacer push a main o publicar un tag vX.Y.Z, la imagen se publica en ghcr.io/serversmx/mcp-evolution-api (docker-publish.yml).

Licencia

MIT