hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Provides a bridge to WhatsApp Web functionality, enabling tools to send/receive messages, search contacts, manage groups, retrieve chat histories, and perform other WhatsApp operations programmatically.

WhatsApp Web MCP

Un puente eficaz 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, lo que facilita la automatización y la mejora de las interacciones en WhatsApp mediante programación.

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.

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 .
Construir con Docker:
docker build . -t wweb-mcp:latest

Configuración

Opciones de línea de comandos

Opción	Alias	Descripción	Opciones	Por defecto
`--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 servidor SSE	-	`3002`
`--api-port`	-	Puerto para el servidor API de WhatsApp	-	`3001`
`--auth-data-path`	`-a`	Ruta para almacenar datos de autenticación	-	`.wwebjs_auth`
`--auth-strategy`	`-s`	Estrategia de autenticación	`local` , `none`	`local`
`--api-base-url`	`-b`	URL base de API para MCP cuando se usa el modo API	-	`http://localhost:3001/api`
`--api-key`	`-k`	Clave API para la API REST de WhatsApp Web al usar el modo API	-	`''`

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:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Para conectar el servidor MCP al servidor API de WhatsApp, debe proporcionar esta clave 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 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.

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:

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

Servidor MCP (independiente)

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

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

Servidor MCP (cliente API)

Ejecute un servidor MCP que se conecte al servidor 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`	Comprobar el estado de conexión del cliente de WhatsApp	Ninguno
`send_message`	Enviar mensajes a contactos de WhatsApp	`number` : Número de teléfono para enviar el `message` : Contenido del 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 se recibirán los mensajes `limit` (opcional): Número de mensajes a recuperar
`get_chats`	Obtenga una lista de todos los chats de WhatsApp	Ninguno
`create_group`	Crea un nuevo grupo de WhatsApp	`name` : Nombre de los `participants` del grupo: Matriz de números de teléfono para agregar
`add_participants_to_group`	Agregar participantes a un grupo existente	`groupId` : ID de los `participants` del grupo: 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 del texto a enviar
`search_groups`	Busque grupos por nombre, descripción o nombres de los miembros	`query` : Término de búsqueda para encontrar grupos
`get_group_by_id`	Obtenga información detallada sobre un grupo específico	`groupId` : ID del grupo a obtener

Recursos disponibles

URI del 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`	Busque grupos por nombre, descripción o nombres de los miembros
`whatsapp://groups/{groupId}/messages`	Mensajes de un grupo específico

Puntos finales de la API REST

Contactos y mensajes

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

Gestión de grupos

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

Integración de IA

Integración de escritorio de Claude

Opción 1: Uso de NPX

Iniciar el servidor API de WhatsApp:
npx wweb-mcp -m whatsapp-api -s local
Escanea el código QR con tu aplicación móvil de WhatsApp
Tenga en cuenta la clave API que se muestra en los registros:
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
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

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
Escanea el código QR con tu aplicación móvil de WhatsApp
Tenga en cuenta la clave API que se muestra en los registros:
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
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" ] } } }
Reiniciar Claude Desktop
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

WhatsAppService : lógica empresarial básica para interactuar con WhatsApp
WhatsAppApiClient : Cliente para conectarse a la API de WhatsApp
Enrutador API : rutas expresas para la API REST
Servidor MCP : Implementación del protocolo de contexto de modelo

Opciones de implementación

Servidor API de WhatsApp : servidor API REST independiente
Servidor MCP (autónomo) : conexión directa a WhatsApp Web
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

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

Construyendo desde la fuente

npm run build

Pruebas

El proyecto utiliza Jest para las 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

Pelusa 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 consistente en todo el proyecto.

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.

Próximas funciones

Crea webhooks para mensajes entrantes y otros eventos de WhatsApp
Soporte para envío de archivos multimedia (imágenes, audio, documentos)
Funciones de gestión de chat grupal
Gestión de contactos (añadir/eliminar contactos)
Plantillas de mensajes para escenarios comunes
Manejo y recuperación de errores mejorados

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Confirme sus cambios
Empujar a tu sucursal
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:

error - Errores críticos que impiden que la aplicación funcione
advertir - Advertencias que no detienen la aplicación pero requieren atención
info - Información general sobre el estado de la aplicación y los eventos
http - Registro de solicitudes/respuestas HTTP
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 :

npm start -- --log-level=debug

O al utilizar la instalación global:

wweb-mcp --log-level=debug

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.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

Un puente que conecta WhatsApp Web con los modelos de IA mediante el Protocolo de Contexto de Modelo, lo que permite que Claude y otros sistemas de IA interactúen con WhatsApp a través de una interfaz estandarizada.