MCP WhatsApp Web (TypeScript)

Un servidor de Protocolo de Contexto de Modelo (MCP) para WhatsApp Web, implementado en TypeScript. Este proyecto es una adaptación a TypeScript del repositorio original de WhatsApp-MCP .

Con este servidor MCP, puedes:

• Busca y lee tus mensajes personales de WhatsApp (incluidos los multimedia)
• Busca tus contactos
• Enviar mensajes a personas o grupos
• Enviar y recibir archivos multimedia (imágenes, vídeos, documentos, audio)

Características

• Implementación de TypeScript : base de código completamente tipificada para una mejor experiencia del desarrollador y confiabilidad del código
• Integración de WhatsApp Web : utiliza whatsapp-web.js para la conexión directa a WhatsApp Web
• Servidor MCP : implementa el protocolo de contexto de modelo para una integración perfecta con asistentes de IA
• Soporte de medios : envíe y reciba imágenes, vídeos, documentos y mensajes de audio.
• Múltiples opciones de transporte : admite transportes stdio y SSE para una integración flexible

Arquitectura

Este servidor MCP consta de:

1. Servidor MCP de TypeScript : implementa el protocolo de contexto de modelo para proporcionar herramientas estandarizadas para que los asistentes de IA interactúen con WhatsApp
2. Servicio web de WhatsApp : se conecta a WhatsApp Web a través de whatsapp-web.js, maneja la autenticación y administra el envío y la recepción de mensajes.
3. Implementaciones de herramientas : proporciona varias herramientas para contactos, chats, mensajes, medios y autenticación.

Prerrequisitos

• Node.js >= 18.0.0
• npm o hilo
• Chrome/Chromium (utilizado por Puppeteer para la conexión web de WhatsApp)
• FFmpeg (opcional, para conversión de mensajes de audio)

Instalación

Instalación manual

1. Clonar este repositorio
   git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git cd mcp-whatsapp-web
2. Instalar dependencias
   npm install
3. Construir el proyecto
   npm run build
4. Configurar variables de entorno (opcional)Copie el archivo de entorno de ejemplo y modifíquelo según sea necesario:
   cp .env.example .env
   Puede ajustar los niveles de registro y especificar rutas a FFmpeg si es necesario.

Instalación con FLUJO

FLUJO ofrece un proceso de instalación optimizado:

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

FLUJO gestionará automáticamente el proceso de clonación, instalación de dependencias y construcción por usted.

Uso

Iniciando el servidor MCP

Esto iniciará el servidor MCP utilizando el transporte stdio de manera predeterminada, lo cual es adecuado para la integración con Claude Desktop o aplicaciones similares.

Importante: Después de iniciar el servidor por primera vez, debe autenticarse con WhatsApp usando la herramienta get_qr_code y escaneando el código QR con su teléfono. Consulte la sección "Autenticación" para obtener instrucciones detalladas.

Modo de desarrollo

Esto inicia el servidor en modo de desarrollo con el modo de observación de TypeScript y se reinicia automáticamente.

Depuración con MCP Inspector

Esto inicia la herramienta Inspector de MCP, que proporciona una interfaz web para probar y depurar su servidor MCP. El inspector le permite:

• Ver todas las herramientas disponibles y sus esquemas
• Ejecute herramientas directamente y vea sus respuestas
• Pruebe su servidor sin necesidad de conectarlo a un asistente de IA
• Ejecución de la herramienta de depuración e inspección de respuestas

Conexión a Claude Desktop

1. Cree un archivo de configuración para Claude Desktop:
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   Reemplace PATH_TO con la ruta absoluta al repositorio.
2. Guarde esto como claude_desktop_config.json en su directorio de configuración de Claude Desktop:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. Reiniciar Claude Desktop

Conectando al cursor

1. Cree un archivo de configuración para Cursor:
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   Reemplace PATH_TO con la ruta absoluta al repositorio.
2. Guarde esto como mcp.json en su directorio de configuración del cursor:
   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json
3. Reiniciar cursor

Autenticación

La primera vez que ejecute el servidor, deberá autenticarse con WhatsApp:

1. Iniciar el servidor MCP
2. Importante: Debes utilizar la herramienta get_qr_code para generar un código QR
   • En Claude u otros asistentes de IA, pide explícitamente "utilizar 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
   • Vaya a Configuración > Dispositivos vinculados > Vincular un dispositivo
   • Apunta la cámara de tu teléfono al código QR que se muestra

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

Estado de autenticación y cierre de sesión

Puede comprobar su estado de autenticación actual y administrar su sesión:

• Utilice la herramienta check_auth_status para verificar si está autenticado actualmente
• Si necesita autenticarse con una cuenta de WhatsApp diferente o volver a autenticarse:
  1. Utilice la herramienta logout para cerrar sesión en su sesión actual
  2. Luego use la herramienta get_qr_code para autenticarse con un nuevo código QR

Esto es particularmente útil cuando:

• Quieres cambiar entre diferentes cuentas de WhatsApp
• Su sesión ha expirado o ha sido invalidada
• Tiene problemas de conexión y necesita volver a autenticarse.

Herramientas MCP disponibles

Autenticación

• get_qr_code - Obtenga el código QR para la autenticación de WhatsApp Web
• check_auth_status - Comprueba si actualmente estás autenticado con WhatsApp
• logout : cerrar sesión en WhatsApp y borrar la sesión actual

Contactos

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

Chats

• list_chats - Lista de chats disponibles con metadatos
• get_chat - Obtener información sobre un chat específico
• get_direct_chat_by_contact - Encuentra 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 - Envía un mensaje de texto a un chat

Medios de comunicación

• send_file - Envía un archivo (imagen, vídeo, documento) a un chat
• send_audio_message - Envía un mensaje de audio (nota de voz)
• download_media - Descargar multimedia desde un mensaje

Gestión de procesos del navegador

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

Limpieza automática del navegador

El servidor automáticamente:

• Realiza un seguimiento de los procesos del navegador Chrome mediante un sistema de seguimiento PID
• Limpia los procesos huérfanos al iniciarse
• 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 observa procesos huérfanos de Chrome que no se limpiaron automáticamente, puede usar la utilidad de limpieza incluida:

Esta utilidad hará lo siguiente:

1. Escanee los procesos de Chrome que podrían estar relacionados con WhatsApp Web
2. Mostrar una lista de procesos potencialmente huérfanos
3. Pide confirmación antes de darlos de baja
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 web de WhatsApp
• src/tools/ - Implementaciones de herramientas para varias funciones de WhatsApp
• src/types/ - Definiciones de tipos de TypeScript
• src/utils/ - Funciones de utilidad

Guiones

• npm run build : compila 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 : detecta y limpia procesos huérfanos del navegador Chrome

Solución de problemas

Problemas de autenticación

• Si el código QR no aparece, intenta reiniciar el servidor
• Si ya está autenticado, no se mostrará ningún código QR (use check_auth_status para verificar)
• Si necesita volver a autenticarse, utilice primero la herramienta logout y luego solicite un nuevo código QR
• WhatsApp limita la cantidad de dispositivos vinculados; es posible que tengas que eliminar un dispositivo existente
• Si recibe un mensaje que dice "No hay ningún código QR disponible actualmente", pero ya está autenticado, este es un comportamiento normal: use check_auth_status para confirmar su estado de autenticación.

Problemas de conexión

• Asegúrese de tener una conexión a Internet estable
• Si la conexión falla, intente reiniciar el servidor
• Consulte los registros para ver mensajes de error detallados

Problemas con el proceso del navegador

• Si nota un alto uso de CPU o consumo de memoria, es posible que haya procesos huérfanos de Chrome.
• Ejecute npm run cleanup-browsers para detectar y limpiar procesos huérfanos
• Si el servidor falla con frecuencia, verifique si hay procesos huérfanos y límpielos
• En Windows, también puedes usar el Administrador de tareas para buscar varios procesos de Chrome con "headless" en la línea de comandos
• En Linux/macOS, use ps aux | grep chrome para verificar si hay procesos huérfanos

Licencia

Instituto Tecnológico de Massachusetts (MIT)

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