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) 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:

{ "query": "Meu amor" }

Resultado de la herramienta:

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

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

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

Resultado de la herramienta:

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

Related MCP server: API Tester MCP Server

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

Instalación mediante herrería

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

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

Clonar este repositorio:
git clone <your-repo-url> whatsapp-mcp-ts cd whatsapp-mcp-ts
Instalar dependencias:
npm install # or yarn install / pnpm install
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 comenzará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.

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}} .
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
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:

Utiliza @whiskeysockets/baileys para conectarse a la API web de WhatsApp, manejando la autenticación y los eventos en tiempo real.
Almacena los 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 AI a través de entrada/salida estándar (stdio).
Proporciona herramientas MCP que consultan la base de datos SQLite local o utilizan el socket Baileys para enviar mensajes.
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 ).

WhatsApp MCP Server