neto-whatsappmcp: avisos por WhatsApp desde tu asistente de IA

Con este proyecto, tu asistente de IA (Claude, Gemini o Codex) puede mandarte un mensaje de WhatsApp. Por ejemplo, cuando termina una tarea larga, cuando necesita que tomes una decisión o cuando algo falla. También puede avisar a tu equipo, mandar un reporte como archivo adjunto y listar tus grupos.

No necesitas saber programar: esta guía te lleva de cero hasta tu primer mensaje, paso a paso. Si sabes usar una terminal (la ventana negra donde se escriben comandos), puedes hacerlo.

Índice

1. ¿Cómo funciona? (con analogías)
2. Qué necesitas instalar
3. Paso a paso: de cero al primer mensaje
4. Personalizar tu API key de Evolution
5. Por qué usamos la versión v2.3.7 de Evolution
6. Variables del archivo .env
7. Conectar tu asistente (Claude, Gemini, Codex)
8. Ejemplos de uso
9. Avisos automáticos con hooks de Claude Code
10. Seguridad
11. Solución de problemas
12. Ventana de configuración (opcional, solo Windows)
13. Para desarrolladores
14. Aviso legal y licencia

1. ¿Cómo funciona? (con analogías)

Hay tres piezas que trabajan en cadena:

Tu asistente de IA  --->  MCP (este proyecto)  --->  Evolution API  --->  WhatsApp
   (el cliente)           puerto 8787                  puerto 8080

Piensa en un restaurante: tu asistente es el cliente que pide, el MCP es el mesero que entiende el pedido y lo traduce, y Evolution es la cocina que sabe hablar con WhatsApp.

Por qué hay dos archivos compose

Si ya tienes tu propio Evolution funcionando, no necesitas el primer archivo: solo apunta EVOLUTION_BASE_URL a tu Evolution. Ojo: docker compose up -d (sin -f) levanta solo el MCP. Para Evolution siempre escribes -f docker-compose.evolution.yml.

2. Qué necesitas instalar

• Docker Desktop (Windows o Mac) o Docker Engine con el plugin Compose (Linux): https://www.docker.com/products/docker-desktop/ . Después de instalarlo, ábrelo y espera a que diga que está funcionando.
• Git, para descargar el proyecto: https://git-scm.com/downloads
• Al menos un asistente de IA que soporte MCP:
  • Claude Code (terminal o extensión de VS Code) o Claude Desktop
  • Gemini CLI
  • Codex CLI
• Un teléfono con WhatsApp (el que vas a vincular).
• Node 24: solo si vas a desarrollar el proyecto o a usar los hooks de Claude Code (sección 9). Para lo demás no hace falta.

Los comandos de esta guía se escriben en una terminal: en Windows usa PowerShell; en Mac o Linux usa la Terminal. Cuando un comando cambia según el sistema, se muestran los dos.

3. Paso a paso: de cero al primer mensaje

Paso 1. Descargar el proyecto

git clone https://github.com/wlnaim/neto-whatsappmcp.git
cd neto-whatsappmcp

Todo lo que sigue se escribe dentro de la carpeta neto-whatsappmcp.

Paso 2. Crear tu archivo .env

El archivo .env guarda tus claves y ajustes. Es tuyo y nunca se sube a GitHub. Se crea copiando la plantilla:

# Windows (PowerShell)
Copy-Item .env.example .env

# Mac / Linux
cp .env.example .env

Paso 3. Inventar tu API key y tu contraseña de base de datos

Necesitas dos textos largos y aleatorios. Genéralos con estos comandos (cada vez que lo ejecutas sale uno distinto):

# Windows (PowerShell): API key
$b = New-Object byte[] 32; (New-Object Security.Cryptography.RNGCryptoServiceProvider).GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') })

Ejecútalo otra vez para obtener la contraseña de la base de datos (es otro texto distinto).

# Mac / Linux
openssl rand -hex 32    # API key
openssl rand -hex 16    # contraseña de la base de datos

Ahora abre el archivo .env con un editor de texto (notepad .env en Windows, nano .env en Mac/Linux) y reemplaza los textos de ejemplo:

EVOLUTION_API_KEY=pega-aquí-el-primer-texto
EVOLUTION_DB_PASSWORD=pega-aquí-el-segundo-texto

Reglas: sin comillas, sin espacios alrededor del = y, en la contraseña, solo letras y números (los textos que generaste ya cumplen esto).

Paso 4. Levantar Evolution

Asegúrate de que Docker Desktop esté abierto y ejecuta:

docker compose -f docker-compose.evolution.yml up -d

La primera vez descarga varios archivos y puede tardar unos minutos. Para comprobar que funciona, abre en tu navegador http://localhost:8080 . Debe aparecer un mensaje parecido a este (en inglés) con el número de versión:

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

Si no abre, espera medio minuto y recarga.

Paso 5. Crear la instancia y vincular tu WhatsApp (el QR)

1. Abre el panel de Evolution: http://localhost:8080/manager/ (viene incluido; no hay que instalar nada más).
2. Para entrar te pide la URL del servidor (http://localhost:8080) y la API key (la que pusiste en EVOLUTION_API_KEY). Los nombres exactos de los campos pueden variar un poco.
3. Crea una instancia nueva: ponle un nombre sencillo, por ejemplo mi-whatsapp (solo letras, números y guiones), y como tipo de conexión elige WHATSAPP-BAILEYS.
4. El panel muestra un código QR. En tu celular abre WhatsApp, entra a Configuración (o Ajustes) > Dispositivos vinculados > Vincular un dispositivo y escanea el QR. Si el QR caduca, genera otro desde el panel.
5. Cuando el panel marque la instancia como conectada (estado open), listo.

Los nombres exactos de los botones del panel pueden cambiar entre versiones y no se verificaron uno por uno (sin verificar). Lo importante es: crear la instancia, ver el QR y escanearlo.

Alternativa sin panel (para quien prefiera la terminal). Reemplaza TU_API_KEY por tu clave:

curl.exe -X POST http://localhost:8080/instance/create -H "apikey: TU_API_KEY" -H "Content-Type: application/json" -d "{\"instanceName\":\"mi-whatsapp\",\"qrcode\":true,\"integration\":\"WHATSAPP-BAILEYS\"}"

(En Mac/Linux usa curl y comillas simples alrededor del JSON: -d '{"instanceName":"mi-whatsapp","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'.) La respuesta incluye el QR en formato base64, que es más cómodo de ver en el panel.

Para comprobar el estado de la conexión: curl.exe -H "apikey: TU_API_KEY" http://localhost:8080/instance/connectionState/mi-whatsapp (verás "state":"open" cuando esté conectada).

Paso 6. Decirle al MCP cuál es tu instancia y tu número

Abre .env otra vez y completa:

EVOLUTION_INSTANCE=mi-whatsapp
WHATSAPP_ME=52XXXXXXXXXX
WHATSAPP_TEAM=

• EVOLUTION_INSTANCE: el nombre exacto que le pusiste a la instancia.
• WHATSAPP_ME: tu número con código de país y solo dígitos: sin +, sin espacios, sin guiones. Ejemplo ficticio de México: 52XXXXXXXXXX (52 = código de país, seguido de tu número). El mensaje te llegará a ti mismo, en el chat "Tú".
• WHATSAPP_TEAM: déjalo vacío (como arriba) si no vas a usar grupos. Más adelante se explica cómo llenarlo.

Deja EVOLUTION_BASE_URL=http://localhost:8080 como está.

Paso 7. Construir y levantar el MCP

docker compose up -d --build

La primera vez construye la imagen whatsapp-mcp (unos minutos). Comprueba que está vivo:

# Windows (PowerShell)
curl.exe http://127.0.0.1:8787/healthz

# Mac / Linux
curl http://127.0.0.1:8787/healthz

Debe responder ok. (También puedes abrir esa dirección en el navegador.)

Paso 8. Mandar tu primer mensaje de prueba

Sin usar todavía ningún asistente, prueba el envío con la herramienta de línea de comandos del proyecto, que corre dentro de Docker:

docker run --rm --env-file .env --entrypoint node whatsapp-mcp dist/cli.js send --to me "Hola desde mi MCP"

Debe imprimir una línea como ✔ 52XXXXXXXXXX enviado y el mensaje llega a tu WhatsApp. Si dice error, ve a la sección 11.

(Si tienes Node 24, también puedes usar npm ci, npm run build y node dist/cli.js send ..., pero entonces las variables del .env deben estar cargadas en tu terminal: Node no lee el .env por sí solo.)

Paso 9. Conectar tu asistente

Sigue la sección 7 con el asistente que uses y pídele: "Avísame por WhatsApp que ya quedó todo listo".

Cómo apagar o encender todo

docker compose down                                          # apaga el MCP
docker compose -f docker-compose.evolution.yml down          # apaga Evolution (conserva tu WhatsApp vinculado)
docker compose up -d                                         # enciende el MCP
docker compose -f docker-compose.evolution.yml up -d         # enciende Evolution

No uses down -v en Evolution: el -v borra los datos (y tendrías que escanear el QR otra vez). Los contenedores arrancan solos cuando Docker Desktop se inicia (restart: unless-stopped).

4. Personalizar tu API key de Evolution

Qué es: la contraseña con la que programas (como este MCP) piden cosas a Evolution. Quien tenga tu API key puede mandar mensajes desde tu WhatsApp, así que debe ser larga, aleatoria y secreta.

La inventas tú. En este proyecto no existe una clave "oficial" ni por defecto: Evolution no arranca si EVOLUTION_API_KEY está vacía (el compose muestra un mensaje de error en español). Así nadie usa por accidente una clave conocida.

Cómo generar una buena (solo letras y números, 64 caracteres):

# Windows (PowerShell, versión 5.1 o superior)
$b = New-Object byte[] 32; (New-Object Security.Cryptography.RNGCryptoServiceProvider).GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') })

# Mac / Linux
openssl rand -hex 32

Dónde se escribe: en un solo lugar, el archivo .env, en la variable EVOLUTION_API_KEY. La misma clave la usan Evolution (para exigirla) y el MCP (para presentarla), por eso no hay que escribirla en dos archivos.

Cómo cambiarla después:

1. Genera una nueva y pégala en .env (EVOLUTION_API_KEY=...).
2. Reinicia las dos piezas para que lean la clave nueva:

docker compose -f docker-compose.evolution.yml up -d
docker compose up -d

Docker detecta que cambió el ajuste y recrea el contenedor automáticamente. En la prueba de esta guía, después de cambiar la clave y ejecutar up -d: la clave vieja dio error 401, la nueva funcionó (200) y la instancia creada antes siguió existiendo (no hubo que volver a crearla). Si usas el panel, entra con la clave nueva.

Nunca la subas a GitHub: el archivo .env está en .gitignore. Si alguna vez la pegas por error en un lugar público, cámbiala de inmediato con los pasos de arriba.

Misma idea para la contraseña de la base de datos

EVOLUTION_DB_PASSWORD se genera igual (usa openssl rand -hex 16 o el comando de PowerShell) y vive solo en .env.

Ojo, aquí hay una diferencia importante: la contraseña se guarda dentro de la base de datos la primera vez que se crea. Si solo cambias el texto en .env, Evolution ya no podrá entrar y se queda reiniciando con un error de autenticación (lo comprobamos: P1000 Authentication failed). Si te pasa, vuelve a poner la contraseña anterior y todo regresa a la normalidad. Para cambiarla de verdad, con Evolution encendido:

docker compose -f docker-compose.evolution.yml exec postgres psql -U evolution -d evolution -c "ALTER USER evolution WITH PASSWORD 'TU_NUEVA_CONTRASEÑA';"

(escribe la nueva contraseña, solo letras y números, sin acentos ni la ñ), luego pon esa misma contraseña en .env y ejecuta docker compose -f docker-compose.evolution.yml up -d. Esa forma conserva tu WhatsApp vinculado y fue la que probamos. La otra opción es borrar los datos con docker compose -f docker-compose.evolution.yml down -v, pero entonces pierdes la vinculación y debes escanear el QR de nuevo.

5. Por qué usamos la versión v2.3.7 de Evolution

En docker-compose.evolution.yml la imagen es evoapicloud/evolution-api:v2.3.7. Esto es lo que pudimos comprobar (consultas hechas el 25 de octubre de 2026):

1. Es la imagen oficial vigente. evoapicloud/evolution-api es la imagen que usa el propio compose del proyecto Evolution y la que mantienen hoy en Docker Hub (https://hub.docker.com/r/evoapicloud/evolution-api). La imagen antigua atendai/evolution-api ya no se encontró en Docker Hub al consultarla. El repositorio de código también cambió de dueño: github.com/EvolutionAPI/evolution-api ahora redirige a github.com/evolution-foundation/evolution-api.
2. v2.3.7 es la última versión estable publicada. Salió el 5 de diciembre de 2025. Las versiones más nuevas que existen son pruebas (marcadas como pre-release en GitHub): 2.4.0-rc1 (6 de mayo de 2026) y 2.4.0-rc2 (17 de mayo de 2026). Sus propias notas dicen "usar solo para validación; no desplegar en producción" y anuncian un cambio importante: la 2.4.0 exige activar una licencia antes de responder (sin activar, devuelve un error 503 LICENSE_REQUIRED). Notas oficiales: https://github.com/evolution-foundation/evolution-api/releases
3. Un número de versión fijo evita sorpresas. Con el tag latest, un día tu instalación podría descargar una versión distinta sin que lo decidas. Hoy latest apunta, en la práctica, al mismo código que la 2.3.7 más cuatro cambios de documentación/licencia (lo revisamos comparando la imagen con el repositorio). Pero si algún día latest pasa a la 2.4.x, tu instalación cambiaría sola. Con v2.3.7 siempre obtienes lo mismo.
4. Es la versión con la que se desarrolló y probó este MCP. Las rutas que usa el MCP (están en src/evolution.ts) son: POST /message/sendText/{instancia}, POST /message/sendMedia/{instancia}, GET /group/fetchAllGroups/{instancia}, GET /instance/connectionState/{instancia}, y la clave viaja en el encabezado apikey. Para esta guía levantamos Evolution v2.3.7 desde cero con el compose incluido y comprobamos que responden las rutas de estado y de grupos, que se puede crear una instancia y que entrega el QR. El envío real de mensajes necesita un WhatsApp vinculado, así que en esa prueba desde cero no se ejecutó; está cubierto por las pruebas automáticas del proyecto (con Evolution simulado) y, en la instalación del autor con esta misma versión, whatsapp_status responde open.
5. El panel /manager ya viene incluido en esta versión (respondió 200 en http://localhost:8080/manager/), así que no hace falta un contenedor extra.
6. Además, las notas de la 2.3.7 mencionan arreglos que interesan a este uso: por ejemplo un error de "Unique constraint failed on the fields: (remoteJid)" al enviar a grupos.

No encontramos un motivo mágico más allá de estos: es la última versión estable, funciona con este MCP y fijarla evita cambios inesperados.

Última versión publicada que encontramos: estable 2.3.7 (2025-12-05); pruebas 2.4.0-rc2 (2026-05-17).

Cómo actualizar en el futuro

1. Lee las notas de la versión nueva (enlace de arriba) y decide si te conviene.
2. Haz una copia de seguridad de la base de datos (comando sin verificar en esta guía): docker compose -f docker-compose.evolution.yml exec -T postgres pg_dump -U evolution evolution > respaldo.sql
3. Cambia el número en docker-compose.evolution.yml, por ejemplo evoapicloud/evolution-api:v2.3.7 por la versión nueva.
4. Descarga y reinicia:

docker compose -f docker-compose.evolution.yml pull
docker compose -f docker-compose.evolution.yml up -d

1. Pruébalo: pídele a tu asistente whatsapp_status (debe decir open) y manda un mensaje de prueba (paso 8).
2. Para volver atrás: pon otra vez el número anterior en el archivo y ejecuta up -d. Ten en cuenta que una versión nueva puede modificar la base de datos, y la vieja quizá no la entienda; por eso conviene el respaldo del paso 2.

6. Variables del archivo .env

El archivo .env se crea copiando .env.example (paso 2).

Cómo llenar WHATSAPP_TEAM: pídele a tu asistente que use whatsapp_list_groups, copia los identificadores de los grupos que quieras (terminan en @g.us) y pégalos separados por comas, junto con números de personas si quieres. Ejemplo: WHATSAPP_TEAM=52XXXXXXXXXX,120363XXXXXXXXXXXXXX@g.us. Después ejecuta docker compose up -d para que el MCP lea el cambio.

7. Conectar tu asistente (Claude, Gemini, Codex)

Hay dos formas de conectar, y puedes elegir la que prefieras:

• Variante HTTP (la más simple): el MCP ya está corriendo con docker compose up -d y el asistente se conecta a http://127.0.0.1:8787/mcp.
• Variante stdio: el asistente inicia su propio contenedor cada vez que lo necesita, con docker run -i --rm --env-file <ruta>/.env whatsapp-mcp. No necesita el compose del MCP encendido, pero sí que la imagen whatsapp-mcp ya esté construida (paso 7). Para esta variante, deja MCP_TRANSPORT=stdio en .env.

En todos los ejemplos, reemplaza C:\ruta\a\neto-whatsappmcp por la carpeta real donde clonaste el proyecto (en Mac/Linux, algo como /ruta/a/neto-whatsappmcp). Para ver tu ruta completa: en PowerShell escribe (Get-Location).Path; en Mac/Linux, pwd. En los archivos JSON las barras invertidas se escriben dobles (C:\\ruta\\a\\...).

Claude Code (terminal) y la extensión de VS Code

HTTP:

claude mcp add --transport http whatsapp http://127.0.0.1:8787/mcp

stdio:

claude mcp add --transport stdio whatsapp -- docker run -i --rm --env-file C:\ruta\a\neto-whatsappmcp\.env whatsapp-mcp

Nota (Claude Code y Codex CLI): En PowerShell, si instalaste Claude Code o Codex con npm, escribe el separador entre comillas simples: '--' (si no, PowerShell lo borra y el comando falla). En Mac/Linux o si el programa se instaló con su instalador oficial, -- funciona tal cual. Aplica igual al comando de Codex CLI que aparece más abajo.

Por defecto queda disponible solo en la carpeta donde lo ejecutas; agrega --scope user justo después de claude mcp add para tenerlo en todos tus proyectos. Verifica con claude mcp list (o escribe /mcp dentro de Claude Code). La extensión de VS Code comparte esa configuración: puedes ejecutar el comando en la terminal integrada o administrar los servidores con /mcp en el panel de chat. También hay un archivo de ejemplo para copiar como .mcp.json en un proyecto: examples/claude-code.mcp.json.

Fuente: https://code.claude.com/docs/en/mcp y https://code.claude.com/docs/en/vs-code

Claude Desktop

Claude Desktop lee un archivo de configuración. Ábrelo desde Settings > Developer > Edit Config, o búscalo en:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Para este archivo usa la variante stdio. Agrega esto dentro de mcpServers (junto a los servidores que ya tengas) y reinicia Claude Desktop por completo:

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "C:\\ruta\\a\\neto-whatsappmcp\\.env", "whatsapp-mcp"]
    }
  }
}

Está también en examples/claude_desktop_config.json. Fuente: https://modelcontextprotocol.io/docs/develop/connect-local-servers

Gemini CLI

HTTP (por la terminal):

gemini mcp add --transport http whatsapp http://127.0.0.1:8787/mcp

Por defecto lo guarda en la carpeta actual (.gemini/settings.json); agrega --scope user para guardarlo en el archivo global ~/.gemini/settings.json (en Windows, .gemini\settings.json dentro de tu carpeta de usuario).

O edita el archivo settings.json a mano. HTTP:

{
  "mcpServers": {
    "whatsapp": { "httpUrl": "http://127.0.0.1:8787/mcp" }
  }
}

stdio:

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "C:\\ruta\\a\\neto-whatsappmcp\\.env", "whatsapp-mcp"]
    }
  }
}

Fuente: documentación oficial de Gemini CLI, https://github.com/google-gemini/gemini-cli (archivo docs/tools/mcp-server.md). Estos pasos se tomaron de esa documentación; Gemini CLI no estaba instalado en la computadora donde se preparó esta guía, así que no se ejecutaron (sin verificar en la práctica). Tampoco se probó gemini mcp add con la variante stdio (sin verificar); para stdio usa el settings.json de arriba.

Codex CLI

HTTP:

codex mcp add whatsapp --url http://127.0.0.1:8787/mcp

stdio:

codex mcp add whatsapp -- docker run -i --rm --env-file C:\ruta\a\neto-whatsappmcp\.env whatsapp-mcp

O edita el archivo ~/.codex/config.toml (en Windows, .codex\config.toml dentro de tu carpeta de usuario). HTTP:

[mcp_servers.whatsapp]
url = "http://127.0.0.1:8787/mcp"

stdio (las comillas simples en TOML evitan problemas con las barras invertidas):

[mcp_servers.whatsapp]
command = "docker"
args = ["run", "-i", "--rm", "--env-file", 'C:\ruta\a\neto-whatsappmcp\.env', "whatsapp-mcp"]

Fuentes: https://learn.chatgpt.com/docs/extend/mcp?surface=cli (la antigua dirección developers.openai.com/codex/mcp redirige ahí) y la ayuda del propio comando (codex mcp add --help), que confirma codex mcp add <nombre> (--url <URL> | -- <COMANDO>...).

Herramientas que obtiene tu asistente

En to puedes poner me (tú), team (todo WHATSAPP_TEAM), un número (solo dígitos, con código de país) o el identificador de un grupo (...@g.us).

8. Ejemplos de uso

Escribe estos pedidos tal cual en tu asistente (o adáptalos). Funcionan igual en los tres; abajo hay ejemplos propios para cada uno.

Escenarios útiles

Ejemplos para Claude (Claude Code, extensión de VS Code, Claude Desktop)

• "Refactoriza el módulo de pagos y, cuando termines, mándame un WhatsApp con qué cambió y si las pruebas pasaron."
• "Ejecuta la suite de pruebas completa. Sea cual sea el resultado, envíame por WhatsApp un documento resultado-pruebas.md con el detalle."
• "Usa whatsapp_list_groups, dime los grupos y espera mi respuesta; después manda al grupo que te indique el resumen de la semana."
• "Trabaja en esto sin preguntarme nada salvo que sea imprescindible. Si te bloqueas, avísame por WhatsApp y explícame qué necesitas."

Ejemplos para Gemini (Gemini CLI)

• "Analiza los logs de la carpeta logs/ y mándame por WhatsApp un resumen con los 5 errores más frecuentes."
• "Revisa con whatsapp_status si mi WhatsApp está conectado; si no lo está, dime cómo reconectar."
• "Genera el reporte de cobertura y envíalo como documento al equipo (team) con el texto 'Reporte de hoy'."
• "Cuando termines de migrar los archivos, avísame por WhatsApp con el número de archivos migrados."

Ejemplos para Codex (Codex CLI)

• "Implementa el endpoint de búsqueda y, al terminar, avísame por WhatsApp con el nombre de la rama de trabajo y el resultado de las pruebas."
• "Si las pruebas fallan, envíame por WhatsApp los nombres de las pruebas que fallaron; si pasan, no me escribas."
• "Despliega a pruebas. Si el despliegue falla, mándame el error a mí; si sale bien, avisa al equipo (team)."
• "Escribe un resumen del cambio en formato Markdown y envíalo como documento llamado cambio.md a me."

Prueba rápida desde la terminal (sin asistente)

docker run --rm --env-file .env --entrypoint node whatsapp-mcp dist/cli.js send --to me "Texto de prueba"

Puedes poner varios destinos separados por coma: --to me,team.

9. Avisos automáticos con hooks de Claude Code

Cuando Claude Code se detiene a esperar un permiso o a que termines de decidir algo, no usa ninguna herramienta, así que un pedido en el prompt no sirve para avisarte. Para eso existen los hooks: pequeños comandos que ejecuta el propio programa en ciertos momentos. Esto solo funciona con Claude Code (no con Gemini ni Codex) y requiere Node 24 y Windows PowerShell.

• Evento Notification (pide un permiso, queda esperando, etc.): manda a me el título, el mensaje y la carpeta de trabajo.
• Evento Stop (Claude terminó su turno): manda a me el último mensaje del asistente, recortado.

Instalación:

1. En la carpeta del proyecto: npm ci y luego npm run build (crea dist/cli.js). El script lee las variables del .env del proyecto automáticamente.
2. Abre examples/hooks.settings.json, reemplaza C:\\ruta\\a\\neto-whatsappmcp por tu carpeta real y copia el bloque hooks dentro de tu archivo de ajustes de Claude Code, %USERPROFILE%\.claude\settings.json (si ya tienes una sección hooks, combina los eventos Notification y Stop).
3. El script examples/hook-notify.ps1 siempre termina sin error, así que un fallo de envío nunca bloquea a Claude Code.

Prueba manual (reemplaza la ruta):

'{"hook_event_name":"Notification","title":"Prueba","message":"Aviso de prueba","cwd":"C:\\proyecto"}' | powershell -NoProfile -ExecutionPolicy Bypass -File "C:\ruta\a\neto-whatsappmcp\examples\hook-notify.ps1"

El evento Stop manda un mensaje al final de cada respuesta; si te resulta mucho, deja solo Notification.

10. Seguridad

• Puertos solo locales. Evolution (8080) y el MCP (8787) se publican solo en 127.0.0.1: únicamente tu propia computadora puede entrar. Postgres y Redis no publican ningún puerto.
• El endpoint HTTP del MCP no tiene contraseña propia. Cualquier programa que corra en tu computadora puede pedirle que mande mensajes desde tu WhatsApp. No lo expongas a la red ni lo publiques en internet.
• Validación de Host. El MCP rechaza (error 403) las peticiones cuyo encabezado Host no sea 127.0.0.1, localhost, [::1] o la dirección que configuraste en MCP_HOST. Es una protección contra ataques desde páginas web (DNS rebinding).
• Tu API key y tu contraseña de base de datos no se versionan. Viven solo en .env, que .gitignore excluye. La imagen del MCP no lleva secretos; todo llega por variables de entorno.
• .env.bak. La ventana de configuración (sección 12) deja una copia .env.bak del archivo anterior, con tus claves. También está ignorada por Git, pero bórrala cuando ya no la necesites.
• Cuida a quién le das acceso. Un asistente con este MCP puede escribir a cualquier número o grupo desde tu cuenta. Revisa los destinatarios de WHATSAPP_TEAM y los permisos que concedes.

11. Solución de problemas

Para ver qué pasa por dentro:

docker compose -f docker-compose.evolution.yml logs
docker compose logs

12. Ventana de configuración (opcional, solo Windows)

Si prefieres llenar el .env con una ventana en lugar de un editor de texto, existe Configure-WhatsAppMCP.ps1. Es opcional y solo funciona en Windows (usa PowerShell y formularios de Windows; no necesita instalar nada).

powershell -ExecutionPolicy Bypass -File .\Configure-WhatsAppMCP.ps1

Así se ve la ventana al abrirla (los datos son de ejemplo; la API key aparece como puntitos para que nadie la lea por encima de tu hombro):

Después de llenar los campos, pulsa Probar conexión. Si todo está bien, abajo de los botones aparece en verde Estado: open (WhatsApp vinculado y listo):

Si la API key no coincide con la de Evolution, verás un mensaje rojo como este; corrige la clave y vuelve a probar (la ventana nunca muestra tu clave en los mensajes):

Qué hace:

• Lee el archivo .env y muestra sus valores en campos (la API key va oculta).
• Probar conexión: consulta a Evolution con tu API key y dice si la instancia está conectada, sin mostrar la clave.
• Guardar: escribe el .env y deja una copia del anterior como .env.bak. Conserva las variables que no conoce.
• Guardar y reiniciar contenedor: guarda y reinicia solo el MCP (docker compose up -d). Si cambiaste la API key, reinicia también Evolution: docker compose -f docker-compose.evolution.yml up -d.

13. Para desarrolladores

Requiere Node 24.

npm ci          # instala las dependencias
npm run build   # compila TypeScript a dist/ (dist/index.js = servidor, dist/cli.js = CLI)
npm test        # compila y ejecuta las pruebas (con Evolution simulado, sin red)

Ejecutar sin Docker (las variables se toman del entorno de tu terminal, no del .env):

node dist/index.js    # stdio por defecto; con MCP_TRANSPORT=http escucha en MCP_PORT

Estructura:

src/                      código: configuración, cliente de Evolution, servidor MCP, entradas index.ts y cli.ts
src/tests/                pruebas con fetch simulado
examples/                 configuraciones para Claude Code y Claude Desktop, hooks y hook-notify.ps1
docker-compose.yml        el servidor MCP
docker-compose.evolution.yml   Evolution + Postgres + Redis
Dockerfile                imagen del MCP
Configure-WhatsAppMCP.ps1 ventana opcional (Windows)
.env.example              plantilla de configuración

14. Aviso legal y licencia

• Usa esto de forma responsable. Está prohibido enviar spam o mensajes a personas que no los esperan.
• Evolution se conecta a WhatsApp imitando a WhatsApp Web; no es la API oficial de Meta. WhatsApp puede bloquear o suspender números que usen herramientas no oficiales o que envíen mensajes masivos. El riesgo es tuyo; úsalo con moderación y, de preferencia, con un número que puedas permitirte perder.
• Licencia: GPL-3.0. Consulta el archivo LICENSE.