Skip to main content
Glama
Evolution API MCP Server

Evolution API MCP Server

by serversmx

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.

Versión del servidor MCP: 0.2.0. Consulta el CHANGELOG.

  • 169 herramientas con cobertura de la API v2 (instancias, mensajes, chats, grupos, perfil, etiquetas, proxy, plantillas Meta, catálogo, webhooks, colas de eventos, Chatwoot y 7 integraciones de chatbot).

  • Contrato verificado contra el código fuente de Evolution API 2.3.7 y 2.4.0-rc2: método, ruta y campos obligatorios de cada herramienta.

  • TypeScript sobre el SDK oficial, transporte stdio.

  • Imagen Docker publicada en GHCR y ejecutable con npx (sin clonar).

  • Multi-instancia: las operaciones sobre instancias aceptan instance; opcionalmente una instancia por defecto.

  • Grupos activables vía EVOLUTION_TOOLS para no saturar el contexto del modelo.

Compatible con Evolution API 2.3.7 y 2.4 (verificado contra 2.4.0-rc2). Las herramientas que solo existen desde 2.4 lo indican en su descripción ("Requires Evolution API 2.4+"); en 2.3.7 responden 404 y el error lo explica.

Requisitos

  • Una instancia de Evolution API v2 y su apikey global.

  • Para npx / local: Node.js 18 o superior. Para Docker: solo Docker.

Related MCP server: mcp-evolution-api

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: server, instance, settings, message, chat, profile, label, group, webhook (72 tools).

  • all → todos los grupos (169 tools).

  • Lista explícita, p.ej. message,chat,group → solo esos.

Grupo

Núcleo

Tools

Herramientas

server

✅

1

verificar que la apikey es la global (/verify-creds)

instance

✅

8

crear (settings planos + webhook), conectar, estado, reiniciar, presencia, logout, borrar, listar

settings

✅

2

leer/escribir settings de la instancia (actualización parcial segura)

message

✅

14

texto, media (imagen/video/documento/audio), audio PTT, sticker, ubicación, contacto, reacción, poll, lista, botones, status, ptv, plantilla Meta, carrusel (2.4+)

chat

✅

18

verificar números, marcar leído/reproducido (2.4+)/no leído, archivar, borrar, presencia, bloquear, foto, base64, buscar chats/mensajes/contactos/recibos, chat por JID, editar, votos de poll (2.4+), canales (2.4+)

profile

✅

8

perfil propio y de negocio, privacidad (actualización parcial segura), nombre/estado/foto

label

✅

2

listar y asignar etiquetas

group

✅

17

crear, participantes, invitaciones, ajustes, quién agrega miembros (2.4+), ephemeral, salir

webhook

✅

2

configurar/leer webhook

proxy

—

2

configurar/leer el proxy de la instancia

template

—

4

crear/editar/borrar/listar plantillas Meta (solo Cloud API)

business

—

2

catálogo y colecciones de WhatsApp Business

websocket

—

2

configurar/leer websocket

rabbitmq

—

2

configurar/leer RabbitMQ

sqs

—

2

configurar/leer AWS SQS

nats

—

2

configurar/leer NATS

kafka

—

2

configurar/leer Kafka

pusher

—

2

configurar/leer Pusher

chatwoot

—

2

configurar (actualización parcial segura)/leer Chatwoot

typebot

—

11

bots + settings + sesiones + ignoreJid + start

openai

—

14

bots + settings + sesiones + ignoreJid + credenciales + modelos

dify

—

10

bots + settings + sesiones + ignoreJid

evolutionbot

—

10

bots + settings + sesiones + ignoreJid

flowise

—

10

bots + settings + sesiones + ignoreJid

n8n

—

10

bots + settings + sesiones + ignoreJid

evoai

—

10

bots + settings + sesiones + ignoreJid

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).

  • Las herramientas que operan sobre una instancia aceptan 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 detalle de validación de Evolution (response.message), no solo "Bad Request". La apikey nunca aparece en logs ni errores.

  • Licencia 2.4: si el servidor 2.4+ no está activado, todas las llamadas a herramientas de negocio responden 503 LICENSE_REQUIRED; el error indica la URL de activación (/manager/login) y que reintentar no sirve.

  • Actualizaciones parciales seguras: settings_set, profile_update_privacy, chatwoot_set, y update/settings_set de los bots exigen en el API todos los campos obligatorios. Si omites alguno, la herramienta lee la configuración actual, la combina con lo que pasaste y envía el objeto completo.

  • Los events de webhook/websocket/rabbitmq/sqs/nats/kafka/pusher siempre se envían: [] (por defecto) significa todos los eventos.

  • message_send_media permite transport: "multipart": recibe base64 en los argumentos MCP y lo convierte en un archivo binario en el campo HTTP file. Para delay, quoted o menciones usa el transporte json (por defecto): Evolution recibe los campos multipart como strings y rechaza esos tipos. Los demás envíos de media aceptan URL/base64 mediante JSON.

  • Se excluyen los receptores de webhooks entrantes, las rutas internas de Baileys/S3, administración de licencias y call/offer, que es un stub y no realiza llamadas. Las rutas exclusivas de develop tampoco se exponen.

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, 503 de licencia, 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/ (eventos, Chatwoot, bots)
  tools/helpers.ts    Utilidades de handlers (body, merge de configuración)
  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 (typebot, openai, dify, evolutionbot, flowise, n8n, evoai) comparten una misma fábrica con campos tipados: los comunes (enabled, triggerType, expire, keepOpen, …) más los propios de cada bot (p.ej. url/typebot, openaiCredsId/botType, webhookUrl/basicAuthPass, agentUrl). El bot por defecto de los settings se indica con fallbackId.

Cambios incompatibles en 0.2.0

  • Bots: create/update ya no reciben config y settings_set ya no recibe settings; los campos van directamente en los argumentos.

  • evolution_message_send_list: values pasa a sections y footerText es obligatorio.

  • evolution_chat_send_presence: delay es obligatorio.

  • evolution_instance_create: settings anidado se reemplaza por campos planos (rejectCall, msgCall, groupsIgnore, …), que es lo que lee el API.

Desarrollo

npm run watch    # compila en modo watch
npm run build    # compila a dist/
npm test         # compila y ejecuta regresiones sin conexión a un servidor
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

Available Tools

64 tools
evolution_chat_archiveC

Archive or unarchive a chat.

Inputs: chat (required), archive (required), lastMessage (required), instance.

evolution_chat_check_numbersB

Check which numbers are registered on WhatsApp.

Inputs: numbers (required), instance.

evolution_chat_delete_messageC

Delete a message for everyone.

Inputs: id (required), fromMe (required), remoteJid (required), instance, +1 more.

evolution_chat_find_chatsC

List chats for the instance.

Inputs: where, instance.

evolution_chat_find_contactsC

Find contacts, optionally filtered.

Inputs: where, instance.

evolution_chat_find_messagesC

Find messages, optionally filtered by chat and paginated.

Inputs: page, where, offset, instance.

evolution_chat_find_statusC

Find status (story) messages, optionally filtered.

Inputs: where, instance.

evolution_chat_mark_readB

Mark one or more messages as read.

Inputs: readMessages (required), instance.

evolution_chat_mark_unreadC

Mark a chat as unread.

Inputs: chat (required), lastMessage (required), instance.

evolution_chat_media_base64B

Get the base64 content of a media message.

Inputs: message (required), instance, convertToMp4.

evolution_chat_profile_picture_urlA

Get the profile picture URL of a number.

Inputs: number (required), instance.

evolution_chat_send_presenceB

Send a presence indicator to a chat (composing/recording/paused).

Inputs: number (required), presence (required), delay, instance.

evolution_chat_update_blockC

Block or unblock a contact.

Inputs: number (required), status (required), instance.

evolution_chat_update_messageC

Edit a previously sent text message.

Inputs: key (required), text (required), number (required), instance.

evolution_group_accept_inviteB

Join a group using an invite code.

Inputs: inviteCode (required), instance.

evolution_group_createC

Create a new group.

Inputs: subject (required), participants (required), instance, description.

evolution_group_fetch_allB

List all groups the instance belongs to.

Inputs: instance, getParticipants.

evolution_group_find_infoC

Get information about a specific group.

Inputs: groupJid (required), instance.

evolution_group_invite_codeA

Get the invite code/link of a group.

Inputs: groupJid (required), instance.

evolution_group_invite_infoA

Get group info from an invite code without joining.

Inputs: inviteCode (required), instance.

evolution_group_leaveB

Leave a group.

Inputs: groupJid (required), instance.

evolution_group_participantsC

List the participants of a group.

Inputs: groupJid (required), instance.

evolution_group_revoke_inviteB

Revoke (regenerate) a group's invite code.

Inputs: groupJid (required), instance.

evolution_group_send_inviteB

Send a group invite to one or more numbers.

Inputs: numbers (required), groupJid (required), description (required), instance.

evolution_group_toggle_ephemeralB

Set disappearing messages timer for a group.

Inputs: groupJid (required), expiration (required), instance.

evolution_group_update_descriptionB

Update a group's description.

Inputs: groupJid (required), description (required), instance.

evolution_group_update_participantB

Add, remove, promote, or demote group participants.

Inputs: action (required), groupJid (required), participants (required), instance.

evolution_group_update_pictureB

Update a group's picture by URL.

Inputs: image (required), groupJid (required), instance.

evolution_group_update_settingB

Update group settings (who can message / edit info).

Inputs: action (required), groupJid (required), instance.

evolution_group_update_subjectB

Update a group's name/subject.

Inputs: subject (required), groupJid (required), instance.

evolution_instance_connectC

Connect an instance and get the QR code / pairing code.

Inputs: number, instance.

evolution_instance_connection_stateB

Get the connection state of an instance (open/connecting/close).

Inputs: instance.

evolution_instance_createC

Create a new WhatsApp instance.

Inputs: instanceName (required), token, number, qrcode, +3 more.

evolution_instance_deleteC

Delete an instance permanently.

Inputs: instance.

evolution_instance_fetchA

List instances (optionally filtered by name or id).

Inputs: instanceId, instanceName.

evolution_instance_logoutA

Log out (disconnect) an instance without deleting it.

Inputs: instance.

evolution_instance_restartC

Restart an instance.

Inputs: instance.

evolution_instance_set_presenceA

Set the global presence of an instance (available/unavailable).

Inputs: presence (required), instance.

evolution_label_findB

List all labels in an instance.

Inputs: instance.

evolution_label_handleC

Add or remove a label on a chat.

Inputs: action (required), number (required), labelId (required), instance.

evolution_message_send_audioB

Send a WhatsApp voice/audio message (PTT) by URL or base64.

Inputs: audio (required), number (required), delay, quoted, +3 more.

evolution_message_send_buttonsB

Send a message with interactive buttons.

Inputs: title (required), number (required), buttons (required), description (required), +6 more.

evolution_message_send_contactB

Send one or more contact cards.

Inputs: number (required), contact (required), instance.

evolution_message_send_listC

Send an interactive list message.

Inputs: title (required), number (required), values (required), buttonText (required), +7 more.

evolution_message_send_locationC

Send a location (latitude/longitude).

Inputs: name (required), number (required), address (required), latitude (required), +6 more.

evolution_message_send_mediaB

Send an image, video, or document by URL or base64.

Inputs: media (required), number (required), mediatype (required), delay, +7 more.

evolution_message_send_pollB

Send a poll with selectable options.

Inputs: name (required), number (required), values (required), selectableCount (required), +5 more.

evolution_message_send_ptvB

Send a PTV (round/instant) video message.

Inputs: video (required), number (required), delay, quoted, +3 more.

evolution_message_send_reactionB

React to a message with an emoji.

Inputs: key (required), reaction (required), instance.

evolution_message_send_statusB

Post a WhatsApp status (story): text, image, video, or audio.

Inputs: type (required), content (required), font, caption, +4 more.

evolution_message_send_stickerB

Send a sticker by URL or base64.

Inputs: number (required), sticker (required), delay, quoted, +3 more.

evolution_message_send_textC

Send a text message to a WhatsApp number.

Inputs: text (required), number (required), delay, quoted, +4 more.

evolution_profile_fetchB

Fetch the profile (name, status, picture) of a number.

Inputs: number (required), instance.

evolution_profile_fetch_businessB

Fetch the business profile of a number.

Inputs: number (required), instance.

evolution_profile_fetch_privacyB

Fetch the instance's privacy settings.

Inputs: instance.

evolution_profile_remove_pictureB

Remove the instance's own profile picture.

Inputs: instance.

evolution_profile_update_nameB

Update the instance's own profile name.

Inputs: name (required), instance.

evolution_profile_update_pictureC

Update the instance's own profile picture by URL.

Inputs: picture (required), instance.

evolution_profile_update_privacyC

Update the instance's privacy settings.

Inputs: last, online, status, profile, +3 more.

evolution_profile_update_statusB

Update the instance's own profile status/about text.

Inputs: status (required), instance.

evolution_settings_findB

Get the current settings of an instance.

Inputs: instance.

evolution_settings_setC

Update behavior settings for an instance.

Inputs: msgCall, instance, readStatus, rejectCall, +5 more.

evolution_webhook_findB

Get the webhook configuration for an instance.

Inputs: instance.

evolution_webhook_setC

Configure the HTTP webhook for an instance.

Inputs: url (required), enabled (required), base64, events, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 64 tools

    Disambiguation5/5

    Each tool targets a specific resource and action with clear prefixes (chat, group, instance, message, profile, settings, webhook). Descriptions further distinguish similar actions like sending different message types.

    Naming Consistency5/5

    All tools follow a consistent 'evolution_<resource>_<action>' snake_case pattern without any deviations or mixed conventions.

    Tool Count2/5

    With 64 tools, the server is overly large for an MCP server. While it covers a wide domain, the count exceeds the recommended range and could be split into smaller, more focused servers.

    Completeness5/5

    The tool surface provides comprehensive coverage of the WhatsApp API including instance management, chat operations, various message types, group management, profile updates, labels, settings, and webhooks. No obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP server that integrates Evolution API to enable WhatsApp messaging, chat management, group operations, and instance control through natural language tools.
      54
      41 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that wraps the Evolution API (WhatsApp) as semantic tools for LLM agents, enabling messaging, chat management, group operations, and instance control via natural language.
      32
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Exposes the full WhatsApp API via Evolution API, enabling message sending, chat history, group management, and more through MCP tools.
      70
      MIT