WhatsApp (TypeScript/Baileys)

Conecta una cuenta personal de WhatsApp a un agente de IA utilizando la API multidispositivo de WhatsApp Web.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de WhatsApp (TypeScript/Baileys)

smithery badge

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

Te permite conectar tu cuenta personal de WhatsApp a un agente de IA (como Anthropic Claude a través de su aplicación de escritorio o Cursor) permitiéndole:

  • Buscar tus mensajes personales de WhatsApp.
  • Buscar tus contactos (individuos, no grupos).
  • Listar tus chats recientes.
  • Recuperar el historial de mensajes de chats específicos.
  • Enviar mensajes a individuos o grupos.

Se conecta directamente a tu cuenta personal de WhatsApp utilizando la API multidispositivo de WhatsApp Web. Todos tus mensajes y detalles 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 tú controlas a través de la interfaz del agente).

(Opcional: Considera añadir una captura de pantalla o GIF similar al ejemplo de referencia aquí)

Ejemplo

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

Asistente: De acuerdo, primero necesito encontrar el contacto. Usando herramienta: whatsapp.search_contacts

{
  "query": "Meu amor"
}

Resultado de la herramienta:

[
  {
    "jid": "5599xxxxxx@s.whatsapp.net",
    "name": "Meu Amor"
  }
]

Asistente: Contacto encontrado. Ahora enviando el mensaje. Usando herramienta: whatsapp.send_message

{
  "recipient": "5599xxxxxx@s.whatsapp.net",
  "message": "Te amo"
}

Resultado de la herramienta:

Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).

Características Principales (Herramientas MCP)

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

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

Instalación

Instalación mediante Smithery

Para instalar WhatsApp MCP Server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

Requisitos previos

  • Node.js: Versión 23.10.0 o superior (según se especifica en package.json). Puedes verificar tu versión con node -v. (Tiene soporte inicial integrado para TypeScript y SQLite)
  • npm (o yarn/pnpm): Normalmente viene con Node.js.
  • Cliente de IA: Aplicación de escritorio de 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. Ejecutar el servidor por primera vez: Usa node para ejecutar el script principal directamente.

    node src/main.ts
    • La primera vez que lo ejecutes, probablemente generará un enlace de código QR usando quickchart.io e intentará abrirlo en tu navegador predeterminado.
    • Escanea este código QR usando tu aplicación móvil de WhatsApp (Configuración > Dispositivos vinculados > Vincular un dispositivo).
    • Las credenciales de autenticación se guardarán localmente en el directorio auth_info/ (este está ignorado por git).
    • Los mensajes comenzarán a sincronizarse y se almacenarán en ./data/whatsapp.db. Esto puede tomar algún tiempo dependiendo del tamaño de tu historial. Revisa wa-logs.txt y la salida de la consola para ver el progreso.
    • Mantén esta ventana de terminal abierta. Después de la sincronización puedes cerrarla.

Configuración para el Cliente de IA

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

  1. Preparar el JSON de configuración: Copia la siguiente estructura JSON. Deberás reemplazar {{PATH_TO_REPO}} con la ruta absoluta al directorio donde clonaste 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: Navega 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: Guarda 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 Cursor: Guarda el JSON como mcp.json en su directorio de configuración:
      • ~/.cursor/mcp.json

  3. Reiniciar Claude Desktop / Cursor: Cierra y vuelve a abrir tu cliente de IA. Ahora debería detectar el servidor MCP "whatsapp" y permitirte usar sus herramientas.

Uso

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

Descripción General de la Arquitectura

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

  1. Usa @whiskeysockets/baileys para conectarse a la API de WhatsApp Web, manejando la autenticación y los eventos en tiempo real.
  2. Almacena 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 de IA a través de entrada/salida estándar (stdio).
  4. Proporciona herramientas MCP que consultan la base de datos SQLite local o usan el socket de Baileys para enviar mensajes.
  5. Usa 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: Tus credenciales de conexión de WhatsApp se almacenan localmente en el directorio ./auth_info/.
  • Mensajes y Chats: Tu historial de mensajes y metadatos de chats se almacenan localmente en el archivo SQLite ./data/whatsapp.db.
  • Datos Locales: Tanto auth_info/ como data/ están incluidos en .gitignore para evitar confirmaciones accidentales. Trata estos directorios como sensibles.
  • Interacción con 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 (por ejemplo, list_messages, send_message). El servidor en sí no envía proactivamente tus datos a ningún otro lugar.

Detalles Técnicos

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

Solución de Problemas

  • Problemas con el Código QR:
    • Si el enlace del código QR no se abre automáticamente, revisa la salida de la consola para encontrar la URL quickchart.io y ábrela manualmente.
    • Asegúrate de escanear el código QR rápidamente con la aplicación de WhatsApp de tu teléfono.
  • Fallos de Autenticación / Sesión Cerrada:
    • Si la conexión se cierra con un error de DisconnectReason.loggedOut, necesitas reautenticarte. Detén el servidor, elimina el directorio ./auth_info/ y reinicia el servidor (node src/main.ts) para obtener un nuevo código QR.
  • Problemas de Sincronización de Mensajes:
    • La sincronización inicial puede tomar tiempo. Revisa wa-logs.txt para ver la actividad.
    • Si los mensajes parecen desincronizados o faltan, es posible que necesites un reinicio completo. Detén el servidor, elimina ambos directorios ./auth_info/ y ./data/, luego reinicia el servidor para reautenticarte y resincronizar el historial.
  • Problemas de Conexión MCP (Claude/Cursor):
    • Verifica dos veces command y args (especialmente {{PATH_TO_REPO}}) en tu claude_desktop_config.json o mcp.json. Asegúrate de que la ruta sea absoluta y correcta.
    • Verifica que Node.js esté correctamente instalado y en el PATH de tu sistema.
    • Revisa los registros del cliente de IA para ver errores relacionados con el inicio del servidor MCP.
    • Revisa los registros de este servidor (mcp-logs.txt) para ver errores relacionados con MCP.
  • Errores al Enviar Mensajes:
    • Asegúrate de que el JID del destinatario sea correcto (por ejemplo, number@s.whatsapp.net para usuarios, groupid@g.us para grupos).
    • Revisa wa-logs.txt para ver errores específicos de Baileys.
  • Problemas Generales: Revisa tanto wa-logs.txt como mcp-logs.txt para ver mensajes de error detallados.

Para problemas adicionales de integración MCP, consulta la documentación oficial de MCP.

Créditos

Licencia

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