Servidor MCP de WhatsApp (TypeScript/Baileys)

Este es un servidor de Protocolo de Contexto de Modelo (MCP) para WhatsApp, creado con TypeScript y utilizando la biblioteca @whiskeysockets/baileys .

Le permite conectar su cuenta personal de WhatsApp a un agente de IA (como Anthropic Claude a través de su aplicación de escritorio o Cursor) lo que le permite:

• Busca tus mensajes personales de WhatsApp.
• Busca tus contactos (individuos, no grupos).
• Enumere sus chats recientes.
• Recuperar el historial de mensajes de chats específicos.
• Envía mensajes a personas o grupos.

Se conecta directamente a tu cuenta personal de WhatsApp mediante la API multidispositivo de WhatsApp Web. Todos tus mensajes y datos de autenticación se almacenan localmente en una base de datos SQLite ( ./data/ ) y en la caché de autenticación ( ./auth_info/ ). Los datos solo se envían al agente de IA conectado cuando este utiliza explícitamente las herramientas MCP proporcionadas (que controlas a través de la interfaz del agente).

(Opcional: considere agregar una captura de pantalla o un GIF similar al ejemplo de referencia aquí)

Ejemplo

Usuario: Envía un mensaje de WhatsApp a "Meu amor" en WhatsApp diciendo "Te amo"

Asistente: Bien, primero necesito encontrar el contacto. Usando la herramienta: whatsapp.search_contacts

Resultado de la herramienta:

Asistente: Encontré el contacto. Estoy enviando el mensaje. Usando la herramienta: whatsapp.send_message

Resultado de la herramienta:

Características principales (herramientas MCP)

El servidor expone las siguientes herramientas al agente de IA conectado:

• search_contacts : busca contactos por nombre o parte del número de teléfono (JID).
• list_messages : recupera el historial de mensajes de un chat específico, con paginación.
• list_chats : enumera tus chats, ordenables por actividad o nombre, filtrables, paginados, opcionalmente incluye detalles del último mensaje.
• get_chat : obtiene información detallada sobre un chat específico.
• get_message_context : recupera los mensajes enviados inmediatamente antes y después de un ID de mensaje específico para el contexto.
• send_message : envía un mensaje de texto a un JID de destinatario específico (usuario o grupo).

Instalación

Prerrequisitos

• Node.js: Versión 23.10.0 o superior (como se especifica en package.json ). Puede comprobar su versión con node -v . (Tiene compatibilidad inicial con TypeScript y SQLite).
• npm (o yarn/pnpm): generalmente viene con Node.js.
• Cliente de IA: aplicación de escritorio Anthropic Claude, Cursor, Cline o Roo Code (u otro cliente compatible con MCP).

Pasos

1. Clonar este repositorio:
   git clone <your-repo-url> whatsapp-mcp-ts cd whatsapp-mcp-ts
2. Instalar dependencias:
   npm install # or yarn install / pnpm install
3. Ejecute el servidor por primera vez: use node para ejecutar el script principal directamente.
   node src/main.ts
   • La primera vez que lo ejecute, probablemente generará un enlace de código QR usando quickchart.io e intentará abrirlo en su navegador predeterminado.
   • Escanee este código QR usando su aplicación móvil WhatsApp (Configuración > Dispositivos vinculados > Vincular un dispositivo).
   • Las credenciales de autenticación se guardarán localmente en el directorio auth_info/ (git ignora esto).
   • Los mensajes empezarán a sincronizarse y se almacenarán en ./data/whatsapp.db . Esto podría tardar un tiempo, dependiendo del tamaño de tu historial. Consulta el archivo wa-logs.txt y la salida de la consola para ver el progreso.
   • Mantén esta ventana de terminal abierta. Después de sincronizar, puedes cerrarla.

Configuración para el cliente de IA

Debes decirle a tu cliente de IA cómo iniciar este servidor MCP.

1. Prepare el JSON de configuración: Copie la siguiente estructura JSON. Deberá reemplazar {{PATH_TO_REPO}} con la ruta absoluta al directorio donde clonó este repositorio.
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "{{PATH_TO_REPO}}/src/main.ts" ], "timeout": 15, // Optional: Adjust startup timeout if needed "disabled": false } } }
   • Obtener la ruta absoluta: Dirígete al directorio whatsapp-mcp-ts en tu terminal y ejecuta pwd . Usa esta salida para {{PATH_TO_REPO}} .
2. Guardar el archivo de configuración:
   • Para Claude Desktop: guarde el JSON como claude_desktop_config.json en su directorio de configuración:
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json (Ruta probable, verificar si es necesario)
     • Linux: ~/.config/Claude/claude_desktop_config.json (Ruta probable, verificar si es necesario)
   • Para el cursor: guarde el JSON como mcp.json en su directorio de configuración:
     • ~/.cursor/mcp.json
3. Reiniciar Claude Desktop/Cursor: Cerrar y volver a abrir el cliente AI. Ahora debería detectar el servidor MCP de WhatsApp y permitirle usar sus herramientas.

Uso

Una vez que el servidor esté en funcionamiento (ya sea manualmente mediante node src/main.ts o iniciado por el cliente de IA mediante el archivo de configuración) y conectado a tu cliente de IA, podrás interactuar con tus datos de WhatsApp a través de la interfaz de chat del agente. Pídele que busque contactos, enumere chats recientes, lea mensajes o los envíe.

Descripción general de la arquitectura

Esta aplicación es un único proceso Node.js que:

1. Utiliza @whiskeysockets/baileys para conectarse a la API web de WhatsApp, manejando la autenticación y los eventos en tiempo real.
2. Almacena los chats y mensajes de WhatsApp localmente en una base de datos SQLite ( ./data/whatsapp.db ) usando node:sqlite .
3. Ejecuta un servidor MCP usando @modelcontextprotocol/sdk que escucha solicitudes de un cliente AI a través de entrada/salida estándar (stdio).
4. Proporciona herramientas MCP que consultan la base de datos SQLite local o utilizan el socket Baileys para enviar mensajes.
5. Utiliza pino para registrar la actividad ( wa-logs.txt para eventos de WhatsApp, mcp-logs.txt para la actividad del servidor MCP).

Almacenamiento de datos y privacidad

• Autenticación: Sus credenciales de conexión de WhatsApp se almacenan localmente en el directorio ./auth_info/ .
• Mensajes y chats: su historial de mensajes y los metadatos del chat se almacenan localmente en el archivo SQLite ./data/whatsapp.db .
• Datos locales: Tanto auth_info/ como data/ se incluyen en .gitignore para evitar confirmaciones accidentales. Estos directorios se consideran confidenciales.
• Interacción LLM: Los datos solo se envían al Modelo de Lenguaje Grande (LLM) conectado cuando el agente de IA utiliza activamente una de las herramientas MCP proporcionadas (p. ej., list_messages o send_message ). El servidor no envía sus datos de forma proactiva a ningún otro lugar.

Detalles técnicos

• Lenguaje: TypeScript
• Tiempo de ejecución: Node.js (>= v23.10.0)
• API de WhatsApp: @whiskeysockets/baileys
• SDK de MCP: @modelcontextprotocol/sdk
• Base de datos: node:sqlite (SQLite incluido)
• Registro: pino
• Validación de esquema: zod (para entradas de la herramienta MCP)

Solución de problemas

• Problemas con el código QR:
  • Si el enlace del código QR no se abre automáticamente, verifique la salida de la consola para la URL de quickchart.io y ábrala manualmente.
  • Asegúrese de escanear el código QR inmediatamente con la aplicación WhatsApp de su teléfono.
• Errores de autenticación/Cierre de sesión:
  • Si la conexión se cierra con un error DisconnectReason.loggedOut , deberá volver a autenticarse. Detenga el servidor, elimine el directorio ./auth_info/ y reinicie el servidor ( node src/main.ts ) para obtener un nuevo código QR.
• Problemas de sincronización de mensajes:
  • La sincronización inicial puede tardar un poco. Consulta la actividad wa-logs.txt .
  • Si los mensajes parecen desincronizados o faltan, es posible que necesite un reinicio completo. Detenga el servidor, elimine los directorios ./auth_info/ y ./data/ y, a continuación, reinicie el servidor para volver a autenticar y sincronizar el historial.
• Problemas de conexión MCP (Claude/Cursor):
  • Verifique el command y args (especialmente {{PATH_TO_REPO}} ) en claude_desktop_config.json o mcp.json . Asegúrese de que la ruta sea absoluta y correcta.
  • Verifique que Node.js esté instalado correctamente y en la RUTA de su sistema.
  • Verifique los registros del cliente AI para ver si hay errores relacionados con el inicio del servidor MCP.
  • Consulte los registros de este servidor ( mcp-logs.txt ) para ver si hay errores relacionados con MCP.
• Errores al enviar mensajes:
  • Asegúrese de que el JID del destinatario sea correcto (por ejemplo, number@s.whatsapp.net para usuarios, groupid@g.us para grupos).
  • Consulte wa-logs.txt para ver errores específicos de Baileys.
• Problemas generales: consulte wa-logs.txt y mcp-logs.txt para obtener mensajes de error detallados.

Para más problemas de integración de MCP, consulte la documentación oficial de MCP .

Créditos

• https://github.com/lharries/whatsapp-mcp Haga lo mismo que esta base de código pero use Go y Python.

Licencia

Este proyecto está licenciado bajo la licencia ISC (ver package.json ).