WhatsApp

Servidor MCP de WhatsApp

Este es un servidor de Protocolo de Contexto de Modelo (MCP) para WhatsApp.

Con esto puedes buscar y leer tus mensajes personales de WhatsApp (incluyendo imágenes, videos, documentos y mensajes de audio), buscar tus contactos y enviar mensajes tanto a individuos como a grupos. También puedes enviar archivos multimedia, incluyendo imágenes, videos, documentos y mensajes de audio.

Se conecta directamente a tu cuenta personal de WhatsApp a través de la API multidispositivo de WhatsApp Web (usando la librería whatsmeow). Todos tus mensajes se almacenan localmente en una base de datos SQLite y solo se envían a un LLM (como Claude) cuando el agente accede a ellos a través de herramientas (que tú controlas).

Aquí tienes un ejemplo de lo que puedes hacer cuando está conectado a Claude.

Para recibir actualizaciones sobre este y otros proyectos en los que trabajo, ingresa tu correo aquí

Instalación

Requisitos previos

• Go
• Python 3.6+
• Aplicación de escritorio Anthropic Claude Desktop (o Cursor)
• UV (gestor de paquetes de Python), instalar con curl -LsSf https://astral.sh/uv/install.sh | sh
• FFmpeg (opcional) - Solo se necesita para mensajes de audio. Si quieres enviar archivos de audio como mensajes de voz reproducibles de WhatsApp, deben estar en formato .ogg Opus. Con FFmpeg instalado, el servidor MCP convertirá automáticamente archivos de audio que no sean Opus. Sin FFmpeg, aún puedes enviar archivos de audio sin procesar usando la herramienta send_file.

Pasos

1. Clona este repositorio

   git clone https://github.com/lharries/whatsapp-mcp.git
   cd whatsapp-mcp
   

2. Ejecuta el puente de WhatsApp

   Navega al directorio whatsapp-bridge y ejecuta la aplicación Go:

   cd whatsapp-bridge
   go run main.go
   

   La primera vez que lo ejecutes, se te pedirá escanear un código QR. Escanea el código QR con tu aplicación móvil de WhatsApp para autenticarte.

   Después de aproximadamente 20 días, es posible que necesites reautenticarte.

3. Conéctate al servidor MCP

   Copia el siguiente JSON con los valores {{PATH}} apropiados:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Para Claude, guarda esto como claude_desktop_config.json en tu directorio de configuración de Claude Desktop en:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Para Cursor, guarda esto como mcp.json en tu directorio de configuración de Cursor en:

   ~/.cursor/mcp.json
   

4. Reinicia Claude Desktop / Cursor

   Abre Claude Desktop y ahora deberías ver WhatsApp como una integración disponible.

   O reinicia Cursor.

Compatibilidad con Windows

Si estás ejecutando este proyecto en Windows, ten en cuenta que go-sqlite3 requiere CGO habilitado para compilar y funcionar correctamente. Por defecto, CGO está deshabilitado en Windows, por lo que debes habilitarlo explícitamente y tener un compilador de C instalado.

Pasos para que funcione:

1. Instala un compilador de C
   Recomendamos usar MSYS2 para instalar un compilador de C para Windows. Después de instalar MSYS2, asegúrate de agregar la carpeta ucrt64\bin a tu PATH.
   → Hay una guía paso a paso disponible aquí.

2. Habilita CGO y ejecuta la aplicación

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go
   

Sin esta configuración, es probable que encuentres errores como:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Descripción general de la arquitectura

Esta aplicación consta de dos componentes principales:

1. Puente Go de WhatsApp (whatsapp-bridge/): Una aplicación Go que se conecta a la API web de WhatsApp, maneja la autenticación mediante código QR y almacena el historial de mensajes en SQLite. Sirve como puente entre WhatsApp y el servidor MCP.

2. Servidor MCP de Python (whatsapp-mcp-server/): Un servidor Python que implementa el Protocolo de Contexto de Modelo (MCP), que proporciona herramientas estandarizadas para que Claude interactúe con los datos de WhatsApp y envíe/reciba mensajes.

Almacenamiento de datos

• Todo el historial de mensajes se almacena en una base de datos SQLite dentro del directorio whatsapp-bridge/store/
• La base de datos mantiene tablas para chats y mensajes
• Los mensajes están indexados para una búsqueda y recuperación eficientes

Uso

Una vez conectado, puedes interactuar con tus contactos de WhatsApp a través de Claude, aprovechando las capacidades de IA de Claude en tus conversaciones de WhatsApp.

Herramientas MCP

Claude puede acceder a las siguientes herramientas para interactuar con WhatsApp:

• search_contacts: Buscar contactos por nombre o número de teléfono
• list_messages: Recuperar mensajes con filtros y contexto opcionales
• list_chats: Listar chats disponibles con metadatos
• get_chat: Obtener información sobre un chat específico
• get_direct_chat_by_contact: Encontrar un chat directo con un contacto específico
• get_contact_chats: Listar todos los chats que involucran a un contacto específico
• get_last_interaction: Obtener el mensaje más reciente con un contacto
• get_message_context: Recuperar el contexto alrededor de un mensaje específico
• send_message: Enviar un mensaje de WhatsApp a un número de teléfono o JID de grupo especificado
• send_file: Enviar un archivo (imagen, video, audio sin procesar, documento) a un destinatario especificado
• send_audio_message: Enviar un archivo de audio como mensaje de voz de WhatsApp (requiere que el archivo sea un archivo .ogg opus o que ffmpeg esté instalado)
• download_media: Descargar medios de un mensaje de WhatsApp y obtener la ruta local del archivo

Funciones de manejo de medios

El servidor MCP admite tanto el envío como la recepción de varios tipos de medios:

Envío de medios

Puedes enviar varios tipos de medios a tus contactos de WhatsApp:

• Imágenes, Videos, Documentos: Usa la herramienta send_file para compartir cualquier tipo de medio compatible.
• Mensajes de voz: Usa la herramienta send_audio_message para enviar archivos de audio como mensajes de voz reproducibles de WhatsApp.
  • Para una compatibilidad óptima, los archivos de audio deben estar en formato .ogg Opus.
  • Con FFmpeg instalado, el sistema convertirá automáticamente otros formatos de audio (MP3, WAV, etc.) al formato requerido.
  • Sin FFmpeg, aún puedes enviar archivos de audio sin procesar usando la herramienta send_file, pero no aparecerán como mensajes de voz reproducibles.

Descarga de medios

Por defecto, solo los metadatos del medio se almacenan en la base de datos local. El mensaje indicará que se envió un medio. Para acceder a este medio, debes usar la herramienta download_media que toma el message_id y chat_jid (que se muestran al imprimir mensajes que contienen el medio), esto descarga el medio y luego devuelve la ruta del archivo que puede abrirse o pasarse a otra herramienta.

Detalles técnicos

1. Claude envía solicitudes al servidor MCP de Python
2. El servidor MCP consulta al puente Go para obtener datos de WhatsApp o directamente a la base de datos SQLite
3. Go accede a la API de WhatsApp y mantiene la base de datos SQLite actualizada
4. Los datos fluyen de vuelta a través de la cadena hasta Claude
5. Al enviar mensajes, la solicitud fluye desde Claude a través del servidor MCP hasta el puente Go y a WhatsApp

Solución de problemas

• Si encuentras problemas de permisos al ejecutar uv, es posible que debas agregarlo a tu PATH o usar la ruta completa al ejecutable.
• Asegúrate de que tanto la aplicación Go como el servidor Python estén ejecutándose para que la integración funcione correctamente.

Problemas de autenticación

• El código QR no se muestra: Si el código QR no aparece, intenta reiniciar el script de autenticación. Si los problemas persisten, verifica si tu terminal admite la visualización de códigos QR.
• WhatsApp ya ha iniciado sesión: Si tu sesión ya está activa, el puente Go se reconectará automáticamente sin mostrar un código QR.
• Límite de dispositivos alcanzado: WhatsApp limita el número de dispositivos vinculados. Si alcanzas este límite, deberás eliminar un dispositivo existente de WhatsApp en tu teléfono (Configuración > Dispositivos vinculados).
• No se cargan mensajes: Después de la autenticación inicial, puede tomar varios minutos cargar tu historial de mensajes, especialmente si tienes muchos chats.
• WhatsApp desincronizado: Si tus mensajes de WhatsApp se desincronizan con el puente, elimina ambos archivos de base de datos (whatsapp-bridge/store/messages.db y whatsapp-bridge/store/whatsapp.db) y reinicia el puente para reautenticarte.

Para obtener ayuda adicional sobre la integración con Claude Desktop, consulta la documentación de MCP. La documentación incluye consejos útiles para revisar registros y resolver problemas comunes.