hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Supports integration with OpenAI Agents Python SDK, enabling OpenAI models to leverage WhatsApp functionality through the MCP interface.
Enables programmatic interaction with WhatsApp Web, providing tools for sending/receiving messages, managing contacts, creating and managing group chats, searching contacts and groups, retrieving message history, and downloading media from messages.
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
- Clonar el repositorio:Copy
- Instalar globalmente o usar con npx:Copy
- Construir con Docker:Copy
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:
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
| Opción | Tipo | Descripción |
|---|---|---|
url | Cadena | La URL del punto final del webhook donde se enviarán los datos del mensaje |
authToken | Cadena (opcional) | Token de autenticación que se incluirá en el encabezado de autorización como token de portador |
filters.allowedNumbers | Matriz (opcional) | Lista de números de teléfono para aceptar mensajes. Si se proporciona, solo los mensajes de estos números activarán el webhook. |
filters.allowPrivate | Booleano (opcional) | Si se envían mensajes privados al webhook. Valor predeterminado: true |
filters.allowGroups | Booleano (opcional) | Si se envían mensajes grupales al webhook. Valor predeterminado: true |
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
| 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 |
download_media_from_message | Descargar multimedia de un mensaje | messageId : ID del mensaje que contiene los medios para descargar |
send_media_message | Enviar un mensaje multimedia a un contacto de WhatsApp | number : Número de teléfono para enviar a source : Fuente de medios con esquema URI (use http:// o https:// para URL, file:// para archivos locales) caption (opcional): Título de texto para los medios |
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 |
/api/send/media | CORREO | Enviar un mensaje de prensa | number : source del destinatario: Origen de medios con esquema URI (use http:// o https:// para URL, file:// para archivos locales) caption (opcional): Título de texto |
/api/messages/{messageId}/media/download | CORREO | Descargar multimedia de un mensaje | Ninguno |
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:Copy
- 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:Copy
- Agregue lo siguiente a su configuración de Claude Desktop:Copy
Opción 2: Usar Docker
- Iniciar el servidor API de WhatsApp en Docker:Copy
- 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:Copy
- Agregue lo siguiente a su configuración de Claude Desktop:Copy
- 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
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:
- Incremento de versión (
patch,minoromajor) - Etiquetado de Git con la versión precedida por 'v' (por ejemplo, v0.2.1)
- Publicar en npm con secretos de GitHub
Para lanzar una nueva versión:
- Vaya a la pestaña Acciones del repositorio de GitHub
- Seleccione el flujo de trabajo "Publicar paquete"
- Haga clic en "Ejecutar flujo de trabajo"
- Elija el tipo de incremento de versión (parche, menor o mayor)
- 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
- 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 :
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.
This server cannot be installed
Una aplicación Node.js que conecta WhatsApp Web con modelos de IA a través del Protocolo de Contexto de Modelo, lo que permite la mensajería automatizada, la gestión de contactos y la funcionalidad de chat grupal a través de flujos de trabajo impulsados por IA.