@jskirk/mcp Whatsapp Evo

WhatsApp MCP Server

MCP server que conecta agentes de AI a WhatsApp usando la librería evolution2-api-sdk.

Permite a un agente de AI enviar y recibir mensajes de WhatsApp de forma controlada, con permisos configurables y validación de whitelist.

Instalación

Paquete npm

npm install -g @jskirk/mcp-whatsapp-evo

Requisitos previos

• Node.js 18+ (preferiblemente 20+)
• npm o yarn
• Una instancia de Evolution API corriendo

Desarrollo (desde el repo)

git clone https://github.com/jskfox/mcp-whatsapp-evo.git
cd mcp-whatsapp-evo
npm install
npm run build

Configuración

La configuración se realiza mediante variables de entorno. Copia .env.example a .env y edita las credenciales:

cp .env.example .env

Variables de entorno

Ejemplo .env

EVOLUTION_HOST=http://localhost:8080
EVOLUTION_API_KEY=mi-api-key
EVOLUTION_INSTANCE_NAME=mi-instancia

PERMISSIONS_TIER=admin

WHITELIST_ENABLED=true
WHITELIST_PHONES=+5491112345678,+5491187654321
[email protected]
WHITELIST_BLOCK_UNKNOWN=true

WEBHOOK_PORT=3000
WEBHOOK_PATH=/webhook
WEBHOOK_TOKEN=mi-token-secreto

Uso

Ejecución con npx (sin instalar)

# Carga variables de entorno desde .env
export $(cat .env | xargs)
npx @jskirk/mcp-whatsapp-evo

# O directamente con dotenv
node -r dotenv/config node_modules/.bin/mcp-whatsapp-evo

Ejecución instalada globalmente

# Después de: npm install -g @jskirk/mcp-whatsapp-evo
mcp-whatsapp-evo

Integración con Editors usando npx

Si prefieres usar npx en lugar del binario global, configura tu editor así:

Windsurf (npx)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bash",
      "args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
    }
  }
}

Cursor (npx)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bash",
      "args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
    }
  }
}

Claude Desktop (npx)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bash",
      "args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
    }
  }
}

VS Code (npx)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bash",
      "args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
    }
  }
}

Crea ~/.env_whatsapp con las variables:

EVOLUTION_HOST=http://localhost:8080
EVOLUTION_API_KEY=mi-api-key
EVOLUTION_INSTANCE_NAME=mi-instancia
PERMISSIONS_TIER=admin
WHITELIST_ENABLED=true
WHITELIST_PHONES=+5491112345678
WEBHOOK_PORT=3000
WEBHOOK_TOKEN=mi-token

Herramientas Disponibles (16 tools)

Mensajería

Instancia

Chats

Grupos

Sistema de Permisos

3 niveles jerárquicos:

admin > send > read

Un agente con tier send puede usar herramientas read y send, pero no admin.

Whitelist

Cuando WHITELIST_ENABLED=true:

• Envíos salientes: Solo puede enviar a números/grupos en la whitelist
• Recepciones entrantes: Si WHITELIST_BLOCK_UNKNOWN=true, ignora mensajes de números no en whitelist

Cuando WHITELIST_ENABLED=false:

• Puede enviar a cualquier número
• recibe de cualquier número

Webhook (Mensajes Entrantes)

El servidor levanta un HTTP server en el puerto configurado (default: 3000).

El endpoint POST /webhook recibe mensajes entrantes de WhatsApp.

Configurar Webhook en Evolution API

En tu Evolution API, configura la URL del webhook:

http://tu-servidor:3000/webhook?token=tu-token-secreto

Formato del Webhook

{
  "event": "messages.upsert",
  "data": {
    "key": {
      "remoteJid": "[email protected]",
      "fromMe": false
    },
    "message": {
      "conversation": "Hola!"
    },
    "pushName": "Nombre"
  }
}

Integración con n8n

Opción 1: n8n como MCP Client

n8n puede usar este MCP server como integración:

1. ** Instala el n8n MCP extension** (si disponible)
2. Configura en n8n settings:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/mcp-whatsapp-evo/dist/index.js"]
    }
  }
}

3. Usa las tools en workflows n8n para enviar mensajes de WhatsApp desde tus automatizaciones.

Opción 2: n8n como Webhook Receiver

Puedes usar n8n para recibir eventos del MCP y procesarlos:

1. El MCP recibe un mensaje entrante por webhook
2. n8n hace polling a los recursos del MCP o recibe notificaciones
3. n8n procesa y actúa según el contenido

Opción 3: HTTP Request Node

Usa el n8n HTTP Request Node para llamar directamente a la Evolution API:

┌─────────────┐      HTTP Request       ┌──────────────┐
│   n8n       │ ──────────────────────► │ Evolution API│
│  Workflow   │                         │   (directo)  │
└─────────────┘                         └──────────────┘

Esta opción es útil si prefieres no usar MCP pero quieres automatizar con n8n.

Casos de Uso

1. Escalation Agent (Man in the Loop)

Cuando un agente necesita ayuda humana:

Agente AI ──send_message──► WhatsApp ──webhook──► Humano
                                        ▲
                                        │
                                    Responde
                                        │
Agente AI ◄──── Continúa ──────────────┘

2. Notificaciones

El agente envía actualizaciones a usuarios:

Agente AI ──send_message──► WhatsApp ──► Usuario

3. Queries

El agente consulta información:

Agente AI ──get_messages──► WhatsApp ◄── Chat History

Logs

Los logs van a stdout/stderr:

[server] Starting WhatsApp MCP server...
[config] Loaded configuration from environment
[sdk] Evolution API SDK initialized
[sdk] Connected to WhatsApp instance
[mcp] Registered 16 tools
[mcp] MCP server started on stdio transport
[webhook] Webhook server running at http://localhost:3000

Troubleshooting

"Instance not connected"

Verifica que tu Evolution API tenga la instancia conectada y el webhook configurado.

"Number not in whitelist"

El número no está en la whitelist. Agrégalo a .env en WHITELIST_PHONES.

"Permission denied"

El tier del agente es insuficiente para esa tool. Aumenta el tier en PERMISSIONS_TIER.

Tests fallan

npm test

Desarrollo

# Instalar dependencias
npm install

# Build
npm run build

# Modo watch
npm run watch

# Lint
npm run lint

# Tests
npm test

Publicar en npm

# Login en npm
npm login

# Publicar (scoped package requiere access)
npm publish --access public

Arquitectura de Seguridad

┌─────────────────────────────────────────────────────────┐
│                    Agente AI                            │
└─────────────────┬───────────────────────────────────────┘
                  │ MCP (stdio)
┌─────────────────▼───────────────────────────────────────┐
│              MCP Server (mcp-whatsapp)                 │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 1. Permission Guard (¿tiene tier suficiente?)    │   │
│  └─────────────────────┬───────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────┐   │
│  │ 2. Whitelist Validator (¿está en lista blanca?) │   │
│  └─────────────────────┬───────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────┐   │
│  │ 3. Sanitizer (¿input seguro?)                   │   │
│  └─────────────────────┬───────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────┐   │
│  │ 4. Evolution SDK (¿respuesta válida?)            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│              Evolution API / WhatsApp                    │
└─────────────────────────────────────────────────────────┘

Licencia

ISC

Autor

Jorge Solano Kirk

• GitHub: jskfox
• Twitter/X: @jskfox
• LinkedIn: jorge.skirk

Hecho con ❤️