Servidor MCP de WhatsApp | Awesome MCP Servers

Conecta tu cuenta personal de WhatsApp a un agente de IA usando la API multidispositivo de WhatsApp Web.

Documentación

Servidor MCP de WhatsApp (TypeScript/Baileys)

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 usando la API de WhatsApp Web para múltiples dispositivos. 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 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: De acuerdo, primero necesito encontrar el contacto. Usando la herramienta: whatsapp.search_contacts

{
  "query": "Meu amor"
}

Resultado de la herramienta:

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

Asistente: Encontré el contacto. Ahora enviando el mensaje. Usando la 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, opcionalmente incluye 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 el Servidor MCP de WhatsApp 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 (como se especifica en package.json). Puedes comprobar 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

Clona este repositorio:

git clone <your-repo-url> whatsapp-mcp-ts
cd whatsapp-mcp-ts

Instala las dependencias:

npm install
# or yarn install / pnpm install

Ejecuta 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/ (esto está ignorado por git).
- Los mensajes comenzarán a sincronizarse y se almacenarán en ./data/whatsapp.db. Esto puede llevar algún tiempo dependiendo del tamaño de tu historial. Revisa el 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.

Prepara 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
    }
  }
}
```
- Obtén la ruta absoluta: Navega al directorio whatsapp-mcp-ts en tu terminal y ejecuta pwd. Usa esta salida para {{PATH_TO_REPO}}.
Guarda 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, verifica si es necesario)
  - Linux: ~/.config/Claude/claude_desktop_config.json (Ruta probable, verifica si es necesario)
- Para Cursor: Guarda el JSON como mcp.json en su directorio de configuración:
  - ~/.cursor/mcp.json
Reinicia 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 a través de node src/main.ts o iniciado por el cliente de IA mediante el 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.

Resumen de la arquitectura

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

Usa @whiskeysockets/baileys para conectarse a la API de WhatsApp Web, manejando la autenticación y los eventos en tiempo real.
Almacena chats y mensajes de WhatsApp localmente en una base de datos SQLite (./data/whatsapp.db) usando node:sqlite.
Ejecuta un servidor MCP usando @modelcontextprotocol/sdk que escucha solicitudes de un cliente de IA a través de la entrada/salida estándar (stdio).
Proporciona herramientas MCP que consultan la base de datos SQLite local o usan el socket de Baileys para enviar mensajes.
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 los metadatos de los 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 tus datos proactivamente a ningún otro lugar.

Detalles técnicos

Lenguaje: TypeScript
Runtime: Node.js (>= v23.10.0)
WhatsApp API: @whiskeysockets/baileys
MCP SDK: @modelcontextprotocol/sdk
Base de datos: node:sqlite (SQLite incluido)
Logging: pino
Validación de esquema: 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 ver 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 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 llevar 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):
- Vuelve a verificar el command y el args (especialmente el {{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 más problemas de integración con MCP, consulta la documentación oficial de MCP.

Créditos

https://github.com/lharries/whatsapp-mcp Haz lo mismo que este código base pero usa go y python.

Licencia

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