WhatsApp Web MCP

Conecta modelos de IA a WhatsApp Web utilizando el Protocolo de Contexto de Modelo (MCP) para automatizar y mejorar las interacciones.

GitHub

Documentación

WhatsApp Web MCP

Un puente potente entre WhatsApp Web y los modelos de IA mediante el Protocolo de Contexto de Modelo (MCP). Este proyecto permite que modelos de IA como Claude interactúen con WhatsApp a través de una interfaz estandarizada, facilitando la automatización y mejora de las interacciones de WhatsApp de forma programática.

Resumen

WhatsApp Web MCP proporciona una integración fluida entre WhatsApp Web y los modelos de IA al:

Crear una interfaz estandarizada mediante el Protocolo de Contexto de Modelo (MCP)
Ofrecer acceso del servidor MCP a la funcionalidad de WhatsApp
Proporcionar opciones de despliegue flexibles mediante modos SSE o de Comando
Soportar tanto la integración directa con el cliente de WhatsApp como la conectividad basada en API

Aviso de responsabilidad

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

Aviso de responsabilidad del proyecto WhatsApp Web:

Este proyecto no está afiliado, asociado, autorizado, respaldado por, ni de ninguna manera oficialmente conectado con WhatsApp ni con cualquiera de sus subsidiarias o afiliados. 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. Tampoco se garantiza que no sea bloqueado al utilizar este método. WhatsApp no permite bots ni clientes no oficiales en su plataforma, por lo que esto no debe considerarse totalmente seguro.

Instalación

Clonar el repositorio:

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

Instalar globalmente o usar con npx:

# Install globally
npm install -g .

# Or use with npx directly
npx .

Compilar con Docker:
```
docker build . -t wweb-mcp:latest
```

Configuración

Opciones de línea de comandos

Opción	Alias	Descripción	Opciones	Predeterminado
`--mode`	`-m`	Modo de ejecución	`mcp`, `whatsapp-api`	`mcp`
`--mcp-mode`	`-c`	Modo de conexión MCP	`standalone`, `api`	`standalone`
`--transport`	`-t`	Modo de transporte MCP	`sse`, `command`	`sse`
`--sse-port`	`-p`	Puerto para el servidor SSE	-	`3002`
`--api-port`	-	Puerto para el servidor de API de WhatsApp	-	`3001`
`--auth-data-path`	`-a`	Ruta para almacenar los datos de autenticación	-	`.wwebjs_auth`
`--auth-strategy`	`-s`	Estrategia de autenticación	`local`, `none`	`local`
`--api-base-url`	`-b`	URL base de la API para MCP al usar el modo api	-	`http://localhost:3001/api`
`--api-key`	`-k`	Clave de API para la API REST de WhatsApp Web al usar el modo api	-	`''`

Autenticación mediante clave de API

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

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

Métodos de autenticación

Autenticación local (recomendada)

Escanear el código QR una vez
Las credenciales persisten entre sesiones
Más estable para operación a largo plazo

Sin autenticación

Método predeterminado
Requiere escaneo del código QR en cada inicio
Adecuado para pruebas y desarrollo

Uso

Modos de ejecución

Servidor de API de WhatsApp

Ejecutar un servidor de API de WhatsApp independiente que expone la funcionalidad de WhatsApp a través de endpoints REST:

npx wweb-mcp --mode whatsapp-api --api-port 3001

Servidor MCP (independiente)

Ejecutar un servidor MCP que se conecta directamente a WhatsApp Web:

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

Servidor MCP (cliente de API)

Ejecutar un servidor MCP que se conecta al servidor de API de WhatsApp:

# First, start the WhatsApp API server and note the API key from the logs
npx wweb-mcp --mode whatsapp-api --api-port 3001

# Then, start the MCP server with the API key
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

Herramientas disponibles

Herramienta	Descripción	Parámetros
`get_status`	Verificar el estado de conexión del cliente de WhatsApp	Ninguno
`send_message`	Enviar mensajes a contactos de WhatsApp	`number`: Número de teléfono al que enviar `message`: Contenido de texto a enviar
`search_contacts`	Buscar contactos por nombre o número	`query`: Término de búsqueda para encontrar contactos
`get_messages`	Recuperar mensajes de un chat específico	`number`: Número de teléfono del que obtener mensajes `limit` (opcional): Número de mensajes a recuperar
`get_chats`	Obtener una lista de todos los chats de WhatsApp	Ninguno
`create_group`	Crear un nuevo grupo de WhatsApp	`name`: Nombre del grupo `participants`: Matriz de números de teléfono para agregar
`add_participants_to_group`	Agregar participantes a un grupo existente	`groupId`: ID del grupo `participants`: Matriz de números de teléfono para agregar
`get_group_messages`	Recuperar mensajes de un grupo	`groupId`: ID del grupo `limit` (opcional): Número de mensajes a recuperar
`send_group_message`	Enviar un mensaje a un grupo	`groupId`: ID del grupo `message`: Contenido de texto a enviar
`search_groups`	Buscar grupos por nombre, descripción o nombres de miembros	`query`: Término de búsqueda para encontrar grupos
`get_group_by_id`	Obtener información detallada sobre un grupo específico	`groupId`: ID del grupo del que obtener información

Recursos disponibles

URI de recurso	Descripción
`whatsapp://contacts`	Lista de todos los contactos de WhatsApp
`whatsapp://messages/{number}`	Mensajes de un chat específico
`whatsapp://chats`	Lista de todos los chats de WhatsApp
`whatsapp://groups`	Lista de todos los grupos de WhatsApp
`whatsapp://groups/search`	Buscar grupos por nombre, descripción o nombres de miembros
`whatsapp://groups/{groupId}/messages`	Mensajes de un grupo específico

Endpoints de la API REST

Contactos y mensajes

Endpoint	Método	Descripción	Parámetros
`/api/status`	GET	Obtener el estado de conexión de WhatsApp	Ninguno
`/api/contacts`	GET	Obtener todos los contactos	Ninguno
`/api/contacts/search`	GET	Buscar contactos	`query`: Término de búsqueda
`/api/chats`	GET	Obtener todos los chats	Ninguno
`/api/messages/{number}`	GET	Obtener mensajes de un chat	`limit` (consulta): Número de mensajes
`/api/send`	POST	Enviar un mensaje	`number`: Destinatario `message`: Contenido del mensaje

Gestión de grupos

Endpoint	Método	Descripción	Parámetros
`/api/groups`	GET	Obtener todos los grupos	Ninguno
`/api/groups/search`	GET	Buscar grupos	`query`: Término de búsqueda
`/api/groups/create`	POST	Crear un nuevo grupo	`name`: Nombre del grupo `participants`: Matriz de números
`/api/groups/{groupId}`	GET	Obtener información detallada sobre un grupo específico	Ninguno
`/api/groups/{groupId}/messages`	GET	Obtener mensajes de un grupo	`limit` (consulta): Número de mensajes
`/api/groups/{groupId}/participants/add`	POST	Agregar miembros a un grupo	`participants`: Matriz de números
`/api/groups/send`	POST	Enviar un mensaje a un grupo	`groupId`: ID del grupo `message`: Contenido del mensaje

Integración con IA

Integración con Claude Desktop

Opción 1: Usando NPX

Iniciar el servidor de API de WhatsApp:
```
npx wweb-mcp -m whatsapp-api -s local
```
Escanear el código QR con la aplicación móvil de WhatsApp

Anotar la clave de API mostrada en los registros:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Agregar lo siguiente a la 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: Usando Docker

Iniciar el servidor de 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

Escanear el código QR con la aplicación móvil de WhatsApp

Anotar la clave de API mostrada en los registros:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Agregar lo siguiente a la 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"
            ]
        }
    }
}

Reiniciar Claude Desktop
La funcionalidad de WhatsApp estará disponible a través de la interfaz de Claude

Arquitectura

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

Componentes

WhatsAppService: Lógica de negocio principal para interactuar con WhatsApp
WhatsAppApiClient: Cliente para conectarse a la API de WhatsApp
Enrutador API: Rutas Express para la API REST
Servidor MCP: Implementación del Protocolo de Contexto de Modelo

Opciones de despliegue

Servidor de API de WhatsApp: Servidor REST API independiente
Servidor MCP (independiente): Conexión directa a WhatsApp Web
Servidor MCP (cliente de API): Conexión al servidor de API de WhatsApp

Esta arquitectura permite escenarios de despliegue flexibles, incluyendo:

Ejecutar el servidor de API y el servidor MCP en diferentes máquinas
Usar el servidor MCP como cliente de un servidor de API existente
Ejecutar todo en una sola máquina para simplicidad

Desarrollo

Estructura del proyecto

src/
├── whatsapp-client.ts     # WhatsApp Web client implementation
├── whatsapp-service.ts    # Core business logic
├── whatsapp-api-client.ts # Client for the WhatsApp API
├── api.ts                 # REST API router
├── mcp-server.ts          # MCP protocol implementation
└── main.ts                # Application entry point

Compilación desde el código fuente

npm run build

Pruebas

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

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Generate test coverage report
npm run test:coverage

Linting y formato

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

# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Format code with Prettier
npm run format

# Validate code (lint + test)
npm run validate

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

Solución de problemas

Problemas de integración con Claude Desktop

No es posible iniciar wweb-mcp en modo independiente de comando en Claude porque Claude abre más de un proceso, varias veces, y cada wweb-mcp necesita abrir una sesión de puppeteer 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 permitir una integración adecuada con Claude.

Funciones próximas

Crear webhooks para mensajes entrantes y otros eventos de WhatsApp
Soporte para enviar archivos multimedia (imágenes, audio, documentos)
Funciones de gestión de chats grupales
Gestión de contactos (agregar/eliminar contactos)
Plantillas de mensajes para escenarios comunes
Manejo de errores y recuperación mejorados

Contribuciones

Hacer un fork del repositorio
Crear una rama de funcionalidad
Realizar los cambios y confirmarlos
Enviar los cambios a su rama
Crear una solicitud de extracción (Pull Request)

Asegúrese de que su PR:

Siga el estilo de código existente
Incluya las pruebas correspondientes
Actualice la documentación según sea necesario
Describa los cambios en detalle

Dependencias

WhatsApp Web.js

Este proyecto utiliza whatsapp-web.js, una biblioteca de cliente JavaScript no oficial para WhatsApp Web que se conecta mediante la aplicación de navegador de WhatsApp Web. Para más información, visite el repositorio de GitHub de whatsapp-web.js.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para más detalles.

Registros

WhatsApp Web MCP incluye un sistema de registro robusto construido con Winston. El sistema de registro proporciona:

Múltiples niveles de registro (error, warn, info, http, debug)
Salida de consola con registros coloreados
Registro de solicitudes/respuestas HTTP para endpoints de API
Manejo estructurado de errores
Niveles de registro sensibles al entorno (desarrollo vs. producción)
Todos los registros dirigidos a stderr al ejecutarse en modo de comando MCP

Niveles de registro

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

error - Errores críticos que impiden el funcionamiento correcto de la aplicación
warn - Advertencias que no detienen la aplicación pero requieren atención
info - Información general sobre el estado y los eventos de la aplicación
http - Registro de solicitudes/respuestas HTTP
debug - Información detallada de depuración

Configuración del nivel de registro

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

npm start -- --log-level=debug

O al usar la instalación global:

wweb-mcp --log-level=debug

Registro en modo de comando

Cuando se ejecuta en modo de comando MCP (--mode mcp --transport command), todos los registros se dirigen a stderr. 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 registros y diagnósticos. Esto garantiza que la comunicación del protocolo MCP a través de stdout no sea interferida por mensajes de registro.

Entorno de pruebas

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