WhatsApp Web

Un servidor MCP para interactuar con WhatsApp Web, que permite enviar y recibir mensajes.

GitHub
24
Prueba este MCPPatrocinado

Documentación

Muy Importante

La automatización de mensajes de WhatsApp sin la API (de Negocios) de Meta va en contra de los Términos de Servicio de WhatsApp. Asumes toda la responsabilidad por todo lo que hagas con este servidor MCP. Es posible que tu cuenta sea marcada/restringida.

MCP WhatsApp Web (TypeScript)

Un servidor de Protocolo de Contexto de Modelo (MCP) para WhatsApp Web, implementado en TypeScript. Este proyecto es un port a TypeScript del repositorio original whatsapp-mcp.

Con este servidor MCP, puedes:

  • Buscar y leer tus mensajes personales de WhatsApp (incluyendo multimedia)
  • Buscar tus contactos
  • Enviar mensajes a individuos o grupos
  • Enviar y recibir archivos multimedia (imágenes, videos, documentos, audio)

image image

Características

  • Implementación en TypeScript: Código completamente tipado para una mejor experiencia de desarrollo y confiabilidad del código
  • Backend de WhatsApp seleccionable: Usa whatsapp-web.js por defecto, con un backend opcional Baileys que funciona sin navegador
  • Servidor MCP: Implementa el Protocolo de Contexto de Modelo para una integración perfecta con asistentes de IA
  • Soporte multimedia: Envía y recibe imágenes, videos, documentos y mensajes de audio
  • Múltiples opciones de transporte: Soporta transportes stdio y HTTP Streamable — incluso ambos a la vez desde un solo proceso (inicia con stdio y configura MCP_HTTP_PORT para exponer adicionalmente http://127.0.0.1:<port>/mcp, o ejecuta solo HTTP con --http)
  • Autenticación flexible: Código QR (como herramienta de imagen MCP), código de emparejamiento (herramienta request_pairing_code, o impreso automáticamente en stderr al inicio mediante WHATSAPP_PAIRING_PHONE_NUMBER), y un flujo OAuth opcional para clientes HTTP (MCP_OAUTH=true) donde la página de autorización del navegador muestra el código QR de WhatsApp — desvincular WhatsApp revoca los tokens para que los clientes se re-autentiquen automáticamente

Arquitectura

Este servidor MCP consiste en:

  1. Servidor MCP TypeScript: Implementa el Protocolo de Contexto de Modelo para proporcionar herramientas estandarizadas para que los asistentes de IA interactúen con WhatsApp
  2. Backend de WhatsApp: Una interfaz de servicio compartida selecciona web.js/Puppeteer o Baileys/WebSocket, maneja la autenticación y gestiona el envío/recepción de mensajes
  3. Implementaciones de herramientas: Proporciona varias herramientas para contactos, chats, mensajes, multimedia y autenticación

Requisitos previos

  • Node.js >= 22.0.0 (se recomienda Node 22 o 24 para la dependencia SQLite de Baileys)
  • npm o yarn
  • Para el backend webjs por defecto: Google Chrome o Microsoft Edge (detección automática; necesario para soporte de códecs de video/GIF; otras operaciones pueden usar el Chromium incluido de Puppeteer)
  • Para baileys: instala dependencias opcionales, incluido el módulo nativo better-sqlite3. No se necesita Chrome, Edge o Chromium en tiempo de ejecución.

FFmpeg se incluye automáticamente a través del paquete npm ffmpeg-static — no se necesita instalación manual. Puedes apuntar la variable de entorno FFMPEG_PATH a tu propio binario para sobrescribirlo.

Instalación

Instalación manual

  1. Clona este repositorio

    git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
cd mcp-whatsapp-web

  2. Instala las dependencias

    npm install

  3. Compila el proyecto

    npm run build

  4. Configura las variables de entorno (opcional)

    Copia el archivo de entorno de ejemplo y modifícalo según sea necesario:

    cp .env.example .env

    Puedes seleccionar el backend con WHATSAPP_BACKEND, ajustar los niveles de registro, fijar la versión de WhatsApp Web o sobrescribir el navegador detectado automáticamente (BROWSER_EXECUTABLE_PATH) y el binario de ffmpeg (FFMPEG_PATH). WHATSAPP_HEADLESS=false muestra la ventana del navegador de web.js, y WHATSAPP_SESSION_DIR reubica su perfil persistente. Usa un directorio de sesión absoluto para mantenerlo consistente entre directorios de trabajo.

Elegir un backend

WHATSAPP_BACKEND=webjs es el predeterminado y conserva las sesiones existentes y los nombres de herramientas MCP. Usa un perfil persistente dedicado de LocalAuth, no tu perfil personal de Chrome. Ahora mantiene el agente de usuario nativo del navegador y los valores predeterminados de gráficos, omite el banner de automatización de Puppeteer y deja habilitado el sandbox del navegador. Los contenedores que requieran deshabilitar el sandbox pueden configurar explícitamente WHATSAPP_NO_SANDBOX=true. Estos ajustes no garantizan que la automatización sea indetectable.

Para usar el backend opcional de Baileys, configura estas variables en la configuración de tu cliente MCP o en .env, luego reinicia el servidor:

WHATSAPP_BACKEND=baileys
BAILEYS_SESSION_DIR=C:/path/to/your/baileys-sessions

BAILEYS_SESSION_DIR tiene como valor predeterminado <working directory>/baileys-sessions; el ejemplo anterior debe reemplazarse con tu propio directorio absoluto. Empareja este backend por separado con get_qr_code o request_pairing_code. La opción existente WHATSAPP_PAIRING_PHONE_NUMBER también funciona. Baileys no puede reutilizar el perfil del navegador de web.js. Puedes volver a webjs y reanudar su sesión existente.

Baileys y SQLite son dependencias opcionales fijadas que se instalan mediante el npm install normal. Si tu gestor de paquetes las omitió, ejecuta npm install --include=optional. SQLite usa un complemento nativo; se requiere un binario precompilado compatible o un conjunto de herramientas de compilación nativa local. Para evitar descargar Chromium al instalar para Baileys o un navegador de sistema existente, usa:

$env:PUPPETEER_SKIP_DOWNLOAD = 'true'
npm install --include=optional
npm run build

En macOS/Linux, el comando de instalación equivalente es PUPPETEER_SKIP_DOWNLOAD=true npm install --include=optional. Seleccionar Baileys carga solo su controlador y nunca inicia ni limpia procesos del navegador. Un backend no disponible produce un error; nunca cambia silenciosamente de controlador ni reintenta un envío a través de otro backend.

Sesiones e historial de Baileys

  • Las credenciales, claves de Signal, contactos, chats y mensajes persisten en BAILEYS_SESSION_DIR/session.sqlite. Mantén todo el directorio privado y fuera del control de versiones. Solo un servidor en ejecución puede ser propietario de un directorio de sesión. Usa directorios separados para cuentas independientes.
  • El apagado normal conserva la sesión. El cierre de sesión explícito o la autenticación no válida borra las credenciales de Baileys y los datos de cuenta almacenados en caché, y revoca sus tokens de acceso OAuth. El estado OAuth HTTP de Baileys se almacena por separado de web.js en BAILEYS_SESSION_DIR/oauth-store.json.
  • get_backend_status informa el backend activo, la autenticación, los recuentos de registros almacenados y el estado de sincronización del historial. Estar conectado no significa que el historial haya terminado de llegar. Un estado de historial available significa que los datos locales están disponibles, no que WhatsApp haya proporcionado un archivo completo.
  • Las herramientas de contactos e historial consultan el almacén local sincronizado. Se solicita la sincronización inicial completa del historial y puede llevar tiempo en cuentas grandes. list_messages puede solicitar hasta 100 mensajes antiguos adicionales cuando un chat conocido tiene menos de los solicitados, con una espera limitada y un período de enfriamiento por chat. Los lotes de historial tardíos se persisten para consultas posteriores. WhatsApp puede proporcionar solo parte del historial de una cuenta.
  • Trata los ID de mensaje devueltos como opacos y usa ID del backend activo. Se admiten entradas heredadas de números de teléfono @c.us, @s.whatsapp.net, grupos e identificadores @lid; los mapeos conocidos de LID/teléfono se persisten. Los ID de mensaje de web.js no se pueden pasar a Baileys ni viceversa.
  • Texto, multimedia, descargas, notas de voz y las herramientas de autenticación existentes usan la misma interfaz MCP. Las entradas de notas de voz deben ser archivos locales o base64; FFmpeg las convierte a Opus/Ogg mono antes de enviarlas. Si la conversión falla, la herramienta informa un error sin enviar un tipo de mensaje diferente.

El backend de Baileys es opcional y está fijado a 7.0.0-rc14. Revisa los cambios ascendentes antes de actualizar, especialmente las migraciones de autenticación y formato de mensajes. Consulta la documentación de Baileys y el historial de versiones.

Instalación con FLUJO

FLUJO proporciona un proceso de instalación simplificado:

  1. Navega a la sección MCP en FLUJO
  2. Haz clic en "Agregar servidor"
  3. Copia y pega esta URL del repositorio de GitHub: https://github.com/mario-andreschak/mcp-whatsapp-web
  4. Haz clic en "Analizar", "Clonar", "Instalar", "Compilar" y "Actualizar servidor"

FLUJO manejará automáticamente la clonación, instalación de dependencias y el proceso de compilación por ti.

Uso

Iniciar el servidor MCP

npm start

Esto iniciará el servidor MCP usando el transporte stdio por defecto, que es adecuado para la integración con Claude Desktop o aplicaciones similares.

Importante: Después de iniciar el servidor por primera vez, debes autenticarte con WhatsApp usando la herramienta get_qr_code y escanear el código QR con tu teléfono. Consulta la sección Autenticación para instrucciones detalladas.

Modo de desarrollo

npm run dev

Esto inicia el servidor en modo de desarrollo con modo de observación de TypeScript y reinicios automáticos del servidor.

Depuración con MCP Inspector

npm run debug

Esto lanza la herramienta MCP Inspector, que proporciona una interfaz web para probar y depurar tu servidor MCP. El inspector te permite:

  • Ver todas las herramientas disponibles y sus esquemas
  • Ejecutar herramientas directamente y ver sus respuestas
  • Probar tu servidor sin necesidad de conectarlo a un asistente de IA
  • Depurar la ejecución de herramientas e inspeccionar respuestas

Conexión a Claude Desktop

  1. Crea un archivo de configuración para Claude Desktop:

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

    Reemplaza PATH_TO con la ruta absoluta al repositorio.

  2. Guarda esto como claude_desktop_config.json en tu directorio de configuración de Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  3. Reinicia Claude Desktop

Conexión a Cursor

  1. Crea un archivo de configuración para Cursor:

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

    Reemplaza PATH_TO con la ruta absoluta al repositorio.

  2. Guarda esto como mcp.json en tu directorio de configuración de Cursor:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %USERPROFILE%\.cursor\mcp.json

  3. Reinicia Cursor

Autenticación

La primera vez que ejecutes el servidor, necesitarás autenticarte con WhatsApp:

  1. Inicia el servidor MCP
  2. Importante: Debes usar la herramienta get_qr_code para generar un código QR
    • En Claude u otros asistentes de IA, pide explícitamente "usar la herramienta get_qr_code para autenticar WhatsApp"
    • El asistente llamará a esta herramienta y mostrará la imagen del código QR
  3. Escanea el código QR con tu aplicación móvil de WhatsApp
    • Abre WhatsApp en tu teléfono
    • Ve a Configuración > Dispositivos vinculados > Vincular un dispositivo
    • Apunta la cámara de tu teléfono al código QR mostrado

Tu sesión se guardará localmente en el directorio whatsapp-sessions y se reutilizará automáticamente en ejecuciones posteriores. Si no te autenticas usando el código QR, no podrás usar ninguna funcionalidad de WhatsApp.

Estado de autenticación y cierre de sesión

Puedes verificar tu estado de autenticación actual y gestionar tu sesión:

  • Usa la herramienta check_auth_status para verificar si estás autenticado actualmente
  • Si necesitas autenticarte con una cuenta de WhatsApp diferente o re-autenticarte:
    1. Usa la herramienta logout para cerrar sesión en tu sesión actual
    2. Luego usa la herramienta get_qr_code para autenticarte con un nuevo código QR

Esto es particularmente útil cuando:

  • Quieres cambiar entre diferentes cuentas de WhatsApp
  • Tu sesión ha expirado o ha sido invalidada
  • Estás experimentando problemas de conexión y necesitas re-autenticarte

Herramientas MCP disponibles

Autenticación

  • get_qr_code- Obtener el código QR para la autenticación de WhatsApp Web
  • check_auth_status- Verificar si estás autenticado actualmente con WhatsApp
  • logout- Cerrar sesión de WhatsApp y limpiar la sesión actual

Contactos

  • search_contacts- Buscar contactos por nombre o número de teléfono
  • get_contact- Obtener información sobre un contacto específico

Chats

  • list_chats- Listar chats disponibles con metadatos
  • get_chat- Obtener información sobre un chat específico
  • get_direct_chat_by_contact- Encontrar un chat directo con un contacto específico

Mensajes

  • list_messages- Recuperar mensajes con filtros opcionales
  • get_message- Obtener un mensaje específico por ID
  • send_message- Enviar un mensaje de texto a un chat

Multimedia

  • send_file- Enviar un archivo (imagen, video, documento) a un chat
  • send_audio_message- Enviar un mensaje de audio (nota de voz)
  • download_media- Descargar multimedia de un mensaje

Gestión de procesos del navegador

Este servidor MCP utiliza Puppeteer para controlar navegadores Chrome para la conectividad con WhatsApp Web. El servidor incluye un sistema robusto de gestión de procesos del navegador para prevenir procesos Chrome huérfanos.

Limpieza automática del navegador

El servidor automáticamente:

  • Rastrea los procesos del navegador Chrome utilizando un sistema de seguimiento de PID
  • Limpia los procesos huérfanos al iniciar
  • Cierra correctamente los procesos del navegador durante el apagado
  • Mantiene un registro de los PID del navegador en .chrome-pids.json

Limpieza manual del navegador

Si notas procesos Chrome huérfanos que no se limpiaron automáticamente, puedes utilizar la utilidad de limpieza incluida:

npm run cleanup-browsers

Esta utilidad:

  1. Escaneará los procesos Chrome que podrían estar relacionados con WhatsApp Web
  2. Mostrará una lista de procesos potencialmente huérfanos
  3. Pedirá confirmación antes de terminarlos
  4. Limpiará el archivo de seguimiento de PID

Desarrollo

Estructura del proyecto

  • src/index.ts- Punto de entrada
  • src/server.ts- Implementación del servidor MCP
  • src/services/whatsapp.ts- Servicio de WhatsApp Web
  • src/tools/- Implementaciones de herramientas para varias funciones de WhatsApp
  • src/types/- Definiciones de tipos TypeScript
  • src/utils/- Funciones de utilidad

Scripts

  • npm run build- Compilar el código TypeScript
  • npm run dev- Ejecutar en modo de desarrollo con vigilancia
  • npm run lint- Ejecutar ESLint
  • npm run format- Formatear código con Prettier
  • npm run cleanup-browsers- Detectar y limpiar procesos Chrome huérfanos
  • npm test - Ejecutar la suite de pruebas unitarias (rápida, sin necesidad de navegador)
  • npm run test:watch - Ejecutar pruebas unitarias en modo de vigilancia durante el desarrollo
  • npm run test:e2e - Compilar y luego ejecutar pruebas de extremo a extremo (inicia el servidor real incluyendo un navegador sin interfaz gráfica)

Solución de problemas

Problemas de autenticación

  • Si el código QR no aparece, intenta reiniciar el servidor
  • Si ya estás autenticado, no se mostrará ningún código QR (usa check_auth_status para verificar)
  • Si necesitas reautenticarte, usa la herramienta logout primero, luego solicita un nuevo código QR
  • WhatsApp limita el número de dispositivos vinculados; es posible que debas eliminar un dispositivo existente
  • Si recibes un mensaje que dice "No hay ningún código QR disponible actualmente", pero ya estás autenticado, esto es un comportamiento normal: usa check_auth_status para confirmar tu estado de autenticación

Problemas de conexión

  • Asegúrate de tener una conexión a internet estable
  • Si la conexión falla, intenta reiniciar el servidor
  • Revisa los registros para ver mensajes de error detallados

Problemas con los procesos del navegador

  • Si notas un alto uso de CPU o consumo de memoria, podría haber procesos Chrome huérfanos
  • Ejecuta npm run cleanup-browsers para detectar y limpiar procesos huérfanos
  • Si el servidor se bloquea con frecuencia, verifica si hay procesos huérfanos y límpialos
  • En Windows, también puedes usar el Administrador de tareas para buscar múltiples procesos Chrome con "headless" en la línea de comandos
  • En Linux/macOS, usa ps aux | grep chrome para verificar procesos huérfanos

Licencia

MIT

Este proyecto es un puerto TypeScript del whatsapp-mcp original de lharries.