WhatsApp Web MCP

Una aplicación Node.js que conecta WhatsApp Web con modelos de IA mediante el Protocolo de Contexto de Modelo (MCP). Este proyecto proporciona una interfaz estandarizada para la interacción programática con WhatsApp, lo que permite la mensajería automatizada, la gestión de contactos y la funcionalidad de chat grupal mediante flujos de trabajo basados en IA.

Descripción general

WhatsApp Web MCP proporciona una integración perfecta entre WhatsApp Web y los modelos de IA mediante:

• Creación de una interfaz estandarizada a través del Protocolo de Contexto de Modelo (MCP)

• Ofrecer acceso al servidor MCP a la funcionalidad de WhatsApp

• Proporcionar opciones de implementación flexibles a través de los modos SSE o Comando

• Admite tanto la integración directa del cliente de WhatsApp como la conectividad basada en API

Descargo de responsabilidad

IMPORTANTE : Esta herramienta es sólo para fines de prueba y no debe utilizarse en entornos de producción.

Descargo de responsabilidad del proyecto WhatsApp Web:

Este proyecto no está afiliado, asociado, autorizado, respaldado ni conectado oficialmente de ninguna manera con WhatsApp ni con ninguna de sus subsidiarias o filiales. El sitio web oficial de WhatsApp se encuentra en whatsapp.com. "WhatsApp", así como los nombres, marcas, emblemas e imágenes relacionados, son marcas registradas de sus respectivos propietarios. Además, no se garantiza que no se le bloquee al usar este método. WhatsApp no permite bots ni clientes no oficiales en su plataforma, por lo que no debe considerarse totalmente seguro.

Recursos de aprendizaje

Para obtener más información sobre el uso de WhatsApp Web MCP en situaciones reales, consulte estos artículos:

• Integración de WhatsApp con IA: Guía para configurar un servidor MCP de WhatsApp

• Integración del SDK de Python de OpenAI Agents con MCP de Anthropic

Instalación

1. Clonar el repositorio:

   git clone https://github.com/pnizer/wweb-mcp.git cd wweb-mcp

2. Instalar globalmente o usar con npx:

   # Install globally npm install -g . # Or use with npx directly npx .

3. Construir con Docker:

   docker build . -t wweb-mcp:latest

Configuración

Opciones de línea de comandos

Autenticación de clave API

Al ejecutarse en modo API, el servidor API de WhatsApp requiere autenticación mediante una clave API. Esta clave se genera automáticamente al iniciar el servidor API de WhatsApp y se muestra en los registros:

Para conectar el servidor MCP al servidor API de WhatsApp, debe proporcionar esta clave API mediante la opción --api-key o -k :

La clave API se almacena en el directorio de datos de autenticación (especificado por --auth-data-path ) y persiste entre reinicios del servidor API de WhatsApp.

Métodos de autenticación

Autenticación local (recomendada)

• Escanee el código QR una vez

• Las credenciales persisten entre sesiones

• Más estable para funcionamiento a largo plazo

Sin autenticación

• Método predeterminado

• Requiere escaneo de código QR en cada inicio

• Adecuado para pruebas y desarrollo.

Configuración de webhook

Puede configurar webhooks para recibir mensajes entrantes de WhatsApp creando un archivo webhook.json en su directorio de datos de autenticación (especificado por --auth-data-path ).

Formato JSON de webhook

Opciones de configuración

Carga útil del webhook

Cuando se recibe un mensaje y pasa los filtros, se enviará una solicitud POST a la URL configurada con la siguiente carga JSON:

Uso

Modos de ejecución

Servidor API de WhatsApp

Ejecute un servidor API de WhatsApp independiente que exponga la funcionalidad de WhatsApp a través de puntos finales REST:

Servidor MCP (independiente)

Ejecute un servidor MCP que se conecte directamente a WhatsApp Web:

Servidor MCP (cliente API)

Ejecute un servidor MCP que se conecte al servidor API de WhatsApp:

Herramientas disponibles

Recursos disponibles

Puntos finales de la API REST

Contactos y mensajes

Gestión de grupos

Integración de IA

Integración de escritorio de Claude

Opción 1: Uso de NPX

1. Iniciar el servidor API de WhatsApp:

   npx wweb-mcp -m whatsapp-api -s local

2. Escanea el código QR con tu aplicación móvil de WhatsApp

3. Tenga en cuenta la clave API que se muestra en los registros:

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

4. Agregue lo siguiente a su configuración de Claude Desktop:

   { "mcpServers": { "whatsapp": { "command": "npx", "args": [ "wweb-mcp", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://localhost:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

Opción 2: Usar Docker

1. Iniciar el servidor API de WhatsApp en Docker:

   docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth

2. Escanea el código QR con tu aplicación móvil de WhatsApp

3. Tenga en cuenta la clave API que se muestra en los registros:

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

4. Agregue lo siguiente a su configuración de Claude Desktop:

   { "mcpServers": { "whatsapp": { "command": "docker", "args": [ "run", "-i", "--rm", "wweb-mcp:latest", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://host.docker.internal:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

5. Reiniciar Claude Desktop

6. La funcionalidad de WhatsApp estará disponible a través de la interfaz de Claude

Arquitectura

El proyecto está estructurado con una clara separación de preocupaciones:

Componentes

1. WhatsAppService : lógica empresarial básica para interactuar con WhatsApp

2. WhatsAppApiClient : Cliente para conectarse a la API de WhatsApp

3. Enrutador API : rutas expresas para la API REST

4. Servidor MCP : Implementación del protocolo de contexto de modelo

Opciones de implementación

1. Servidor API de WhatsApp : servidor API REST independiente

2. Servidor MCP (autónomo) : conexión directa a WhatsApp Web

3. Servidor MCP (cliente API) : Conexión al servidor API de WhatsApp

Esta arquitectura permite escenarios de implementación flexibles, que incluyen:

• Ejecución del servidor API y del servidor MCP en diferentes máquinas

• Usar el servidor MCP como cliente de un servidor API existente

• Ejecutar todo en una sola máquina para simplificar

Desarrollo

Estructura del proyecto

Construyendo desde la fuente

Pruebas

El proyecto utiliza Jest para las pruebas unitarias. Para ejecutar las pruebas:

Pelusa y formato

El proyecto utiliza ESLint y Prettier para la calidad y el formato del código:

La configuración de linting aplica las mejores prácticas de TypeScript y mantiene un estilo de código consistente en todo el proyecto.

Publicación

El proyecto utiliza GitHub Actions para la publicación automatizada en npm. El flujo de trabajo gestiona:

1. Incremento de versión ( patch , minor o major )

2. Etiquetado de Git con la versión precedida por 'v' (por ejemplo, v0.2.1)

3. Publicar en npm con secretos de GitHub

Para lanzar una nueva versión:

1. Vaya a la pestaña Acciones del repositorio de GitHub

2. Seleccione el flujo de trabajo "Publicar paquete"

3. Haga clic en "Ejecutar flujo de trabajo"

4. Elija el tipo de incremento de versión (parche, menor o mayor)

5. Haga clic en "Ejecutar flujo de trabajo" para iniciar el proceso de publicación.

Este flujo de trabajo requiere que se configure un secreto NPM_TOKEN en su repositorio de GitHub.

Solución de problemas

Problemas de integración de Claude Desktop

• No es posible iniciar wweb-mcp en modo independiente de comandos en Claude porque este abre más de un proceso varias veces, y cada wweb-mcp necesita abrir una sesión de Puppetteer que no puede compartir la misma autenticación de WhatsApp. Debido a esta limitación, hemos dividido la aplicación en modos MCP y API para facilitar su integración con Claude.

Características

• Envío y recepción de mensajes

• Envío de mensajes multimedia (solo imágenes)

• Descargar multimedia de mensajes (imágenes, audio, documentos)

• Gestión de chats grupales

• Gestión y búsqueda de contactos

• Recuperación del historial de mensajes

Próximas funciones

• Soporte para enviar todo tipo de archivos multimedia (video, audio, documentos)

• Plantillas de mensajes mejoradas para escenarios comunes

• Funciones avanzadas de gestión de grupos

• Gestión de contactos (añadir/eliminar contactos)

• Manejo y recuperación de errores mejorados

Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Confirme sus cambios

4. Empujar a tu sucursal

5. Crear una solicitud de extracción

Por favor asegúrese de su PR:

• Sigue el estilo de código existente

• Incluye pruebas apropiadas

• Actualiza la documentación según sea necesario

• Describe los cambios en detalle.

Dependencias

WhatsApp Web.js

Este proyecto utiliza whatsapp-web.js , una biblioteca cliente JavaScript no oficial para WhatsApp Web que se conecta a través de la app de WhatsApp Web para navegadores. Para más información, visita el repositorio de GitHub de whatsapp-web.js .

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Explotación florestal

WhatsApp Web MCP incluye un robusto sistema de registro desarrollado con Winston. Este sistema proporciona:

• Múltiples niveles de registro (error, advertencia, información, http, depuración)

• Salida de consola con registros coloreados

• Registro de solicitudes/respuestas HTTP para puntos finales de API

• Manejo estructurado de errores

• Niveles de registro conscientes del medio ambiente (desarrollo vs. producción)

• Todos los registros se dirigen a stderr cuando se ejecuta en modo de comando MCP

Niveles de registro

La aplicación admite los siguientes niveles de registro, en orden de verbosidad:

1. error - Errores críticos que impiden que la aplicación funcione

2. advertir - Advertencias que no detienen la aplicación pero requieren atención

3. info - Información general sobre el estado de la aplicación y los eventos

4. http - Registro de solicitudes/respuestas HTTP

5. depuración : información de depuración detallada

Configuración del nivel de registro

Puede configurar el nivel de registro al iniciar la aplicación utilizando el indicador --log-level o -l :

O al utilizar la instalación global:

Registro del modo de comando

Al ejecutarse en modo de comando MCP ( --mode mcp --transport command ), todos los registros se redirigen a la salida estándar (stdout). Esto es importante para las herramientas de línea de comandos, donde stdout podría usarse para la salida de datos, mientras que stderr se usa para el registro y el diagnóstico. Esto garantiza que la comunicación del protocolo MCP a través de stdout no se vea interferida por los mensajes de registro.

Entorno de prueba

En entornos de prueba (cuando NODE_ENV=test o cuando se ejecuta con Jest), el registrador ajusta automáticamente su comportamiento para ser adecuado para los entornos de prueba.