WhatsApp MCP Stream


Un servidor de Interfaz de Contexto de Protocolos (MCP) de WhatsApp construido al rededor del transporte Streamable HTTP, usando Baileys para la conexión con WhatsApp, con un interfaz de administración web y flujo bidirccional de archivos multimedia (subida + descarga).

Puntos claves:

• Transporte: Streamable HTTP en /mcp

• Motor: Baileys

• Interfaz de administración: QR, estdo, cierre de sesión, ajustes de ejecución, visor de historial de chats

• Archivos: endpoints de subida + alojamiento /media + herramienta de descarga MCP

Inicio rápido (Docker)

# build and run

docker compose build

docker compose up -d

El servidor estará disponible en:

• Interfaz de administración: http://localhost:3003/admin

• Punto de acceso MCP: http://localhost:3003/mcp

• Archivos multimedi: http://localhost:3003/media/<file>

Related MCP server: lingtai-whatsapp

DNS en hosts con --iptables=false

En algunos hosts NAS o más seguros (pad e: j. sinología con dockerd --iptables=false), el proxy DNS limitado por Docker (127.0.0.11) no dispone de reglas de enmascarado para iptables y rechaza las conexiones dentro de los contenedores.

Solución: copie resolv.conf.example a resolv.conf y añada una anulación de volumen:

cp resolv.conf.example resolv.conf

Después, añadalo a un docker-compose.override.yml local (no versionado):

services:
  mcp-whatsapp:
    volumes:
      - ./resolv.conf:/etc/resolv.conf:ro

docker compose up recoge la anulación automáticamente.

Ajustes de ejecución

Los ajustes se pueden editar en la interfaz de administración y se guardan en SETTINGS_PATH (por defecto, MEDIA_DIR/settings.json).

Interfaz de administración

Panel de administración con ajustes de ejecucción, vinculación de QR, visor de historial de chats, exportación y estado.

Estatutos admitidos:

• media_public_base_url

• upload_max_mb

• upload_enabled

• max_files_per_upload

• require_upload_token

• upload_token

• auto_download_media

• auto_download_max_mb

Autenticación

La autenticación integrada todavía no está implementada. En producción, use una pasare que imponga la autenticación. Este proyecto funciona bien detrás de authmcp-gateway:

https://github.com/loglux/authmcp-gateway

API de subida de archivos multimedia

Base64 JSON:

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:<base64>}

Multipart (recomendado para archivos grandes):

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

Ambos devuelven url y (si está configurado) publicUrl.

Envío de archivos locales mediante send\_media

El directorio ./files/ en la raíz del proyecto está montado dentro del contenedor en /app/files. Coloque cualquier archivo ahí y refiera a él inmediatamente — no necesita reiniciar el contenedor:

# On host:
cp report.pdf /path/to/whatsapp-mcp-stream/files/

# In send_media:
media_path: /app/files/report.pdf

Para un origen HTTPS, pase media_url directamente a send_media o stage_media — el servidor descargará el propio archivo sin base64.

Autenticación de subida (Opcional)

Si require_upload_token=true, proporcione el token con cualquiera de estas opciones:

• x-upload-token: <token>

• Authorization: Bearer <token>

Transporte MCP

El servidor expone Streamable HTTP en /mcp.

Flujo típico:

1. POST /mcp con JSON-RPC initialize

2. Use el encabezado mcp-session-id devuelto para las solicitudes posteriores

3. POST /mcp para llamadas de herramientas

Nota: los clientes deben enviar Accept: application/json, text/event-stream en initialize.

Prueba de humo

Prueba de humo de regresión rápida para las herramientas MCP:

npm run smoke:mcp

Destino personalizado opcional:

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

Herramientas MCP

Autenticación

Contactos

Chat

Mensajes

Archivos

Utilidades

Ajustes de recuperación

Este servicio contiene una solución de recuperación diseñada para corrupción del estado de sesión de Baileys/WhatsApp.

Por qué existe:

• En producción observamos casos en los que el contenedor permanecía activo y el MCP respondía, pero la sesión de WhatsApp estaba funcionalmente rota.

• Los indicadores más comunes eran errores de Baileys como failed to find key ... to decode mutation y failed to sync state from version.

• En ese estado, un reinicio manual del contenedor a menudo restablecía el servicio.

Comportamiento actual:

• Cuando aparecen señales de corrupción del estado de la aplicación, el servicio primero intenta una recuperación suave con forceResync().

• Si la misma clase de error se repite dentro de una ventana de tiempo, llega a un reinicio interno del cliente de WhatsApp.

• En desconexiones como Connection Terminated, el servicio programa un watchdog de desconexión y salta a un reinicio interno si la conexión no vuelve a open a tiempo.

• El ciclo de reconexión está protegido contra los bloqueos de bloqueo anidados, por lo que la recuperación de desconexiones puede completarse sin requerir un reinicio manual del contenedor.

• Observaciones recientes en producción muestran que los socket desconexiones repetidas (428 Connection Terminated, 503 Stream Errored) se recuperan automáticamente volviendo a open.

• Un endpoint dedicado /healthz solo reporta 503 cuando el servicio está genuinamente bloquedo fuere de la ventana de recuperación permitida.

• Docker comprueba la salud usando /healthz, por lo que container se reinicia solo después de que la recuperación en proceso ha tenido la oportunidad de funcionar.

Estos meónismos de recuperación reducen la intervención manual y mejoran la resiliencia frente a fallos comunes de sesión de WhatsApp/Baileys.

Licencia

MIT

Persistencia

Los chats y los mensajes se persisten en una base de datos SQLite local almacenada en el volúmen de sesión.

Variables de entorno:

Diagnósticos adicionales del transporte:

• Las solicitudes POST de /mcp registran ahora los eventos del ciclo de vida de las solicitudes en logs/mcp-whatsapp.log

• esto incluye la entrada de la solicitud, el despacho del transporte, la finalización de transport.handleRequest y los eventos HTTP finish / close

• utiliza estos registros para determinar si la latencia se produce antes de que la respuesta salga de whatsapp-mcp-stream o después, en el lado de la puerta de enlace o del cliente

API de historial de chats

Consulta los chats y mensajes almacenados mediante:

GET /api/chats?limit=50&offset=0&q=<search> — lista de chats paginada, opcionalmente filtrada por nombre.

GET /api/chats/:jid/messages?limit=50&offset=0 — mensajes paginados para un chat (del más nuevo al más antiguo).

Ambos endpoints son utilizados por la pestaña Chats de la interfaz de administración.

Exportación

Exporta un chat (JSON y medios descargados adicionales) mediante:

GET /api/export/chat/:jid?include_media=true

Si include_media=true, el ZIP incluye los archivos ya descargados mediante download_media. No obtiene de WhatsApp los medios faltantes.