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.
에이전트 강화
게시자의 자체 명령입니다. PlugMCP 엔드포인트가 아닙니다.
Host a copy with our keys and logs.
npx -y @jskirk/[email protected]Claude Code에는 로컬 명령용 설치 링크가 없습니다. 아래 명령을 복사해 터미널에서 실행합니다.
claude mcp add jskirk-mcp-whatsapp-evo -- npx -y @jskirk/mcp-whatsapp-evo@1.0.3터미널에서 실행합니다.
{ "mcpServers": { "jskirk-mcp-whatsapp-evo": { "command": "npx", "args": [ "-y", "@jskirk/[email protected]" ] } }}claude_desktop_config.json
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
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.
MCP server for WhatsApp integration using evolution2-api-sdk. Connect AI agents to WhatsApp with permission controls and whitelist validation.
npm install -g @jskirk/mcp-whatsapp-evo
git clone https://github.com/jskfox/mcp-whatsapp-evo.git
cd mcp-whatsapp-evo
npm install
npm run build
La configuración se realiza mediante variables de entorno. Copia .env.example a .env y edita las credenciales:
cp .env.example .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
# 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
# Después de: npm install -g @jskirk/mcp-whatsapp-evo
mcp-whatsapp-evo
Si prefieres usar npx en lugar del binario global, configura tu editor así:
{
"mcpServers": {
"whatsapp": {
"command": "bash",
"args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
}
}
}
{
"mcpServers": {
"whatsapp": {
"command": "bash",
"args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
}
}
}
{
"mcpServers": {
"whatsapp": {
"command": "bash",
"args": ["-c", "source ~/.env_whatsapp && npx @jskirk/mcp-whatsapp-evo"]
}
}
}
{
"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
3 niveles jerárquicos:
admin > send > read
Un agente con tier send puede usar herramientas read y send, pero no admin.
Cuando WHITELIST_ENABLED=true:
WHITELIST_BLOCK_UNKNOWN=true, ignora mensajes de números no en whitelistCuando WHITELIST_ENABLED=false:
El servidor levanta un HTTP server en el puerto configurado (default: 3000).
El endpoint POST /webhook recibe mensajes entrantes de WhatsApp.
En tu Evolution API, configura la URL del webhook:
http://tu-servidor:3000/webhook?token=tu-token-secreto
{
"event": "messages.upsert",
"data": {
"key": {
"remoteJid": "[email protected]",
"fromMe": false
},
"message": {
"conversation": "Hola!"
},
"pushName": "Nombre"
}
}
n8n puede usar este MCP server como integración:
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["/path/to/mcp-whatsapp-evo/dist/index.js"]
}
}
}
Puedes usar n8n para recibir eventos del MCP y procesarlos:
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.
Cuando un agente necesita ayuda humana:
Agente AI ──send_message──► WhatsApp ──webhook──► Humano
▲
│
Responde
│
Agente AI ◄──── Continúa ──────────────┘
El agente envía actualizaciones a usuarios:
Agente AI ──send_message──► WhatsApp ──► Usuario
El agente consulta información:
Agente AI ──get_messages──► WhatsApp ◄── Chat History
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
Verifica que tu Evolution API tenga la instancia conectada y el webhook configurado.
El número no está en la whitelist. Agrégalo a .env en WHITELIST_PHONES.
El tier del agente es insuficiente para esa tool. Aumenta el tier en PERMISSIONS_TIER.
npm test
# Instalar dependencias
npm install
# Build
npm run build
# Modo watch
npm run watch
# Lint
npm run lint
# Tests
npm test
# Login en npm
npm login
# Publicar (scoped package requiere access)
npm publish --access public
┌─────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────┘
ISC
Jorge Solano Kirk
Hecho con ❤️
MCP server for WhatsApp integration using evolution2-api-sdk. Connect AI agents to WhatsApp with permission controls and whitelist validation.
{ "mcpServers": { "jskirk-mcp-whatsapp-evo": { "command": "npx", "args": [ "-y", "@jskirk/[email protected]" ] } }}도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
@jskirk/mcp Whatsapp Evo은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-11-16. MCP server for WhatsApp integration using evolution2-api-sdk. Connect AI agents to WhatsApp with permission controls and whitelist validation.