WhatsApp MCP

Envía y recibe mensajes usando la API de WhatsApp.

GitHub
6.4k
Prueba este MCPPatrocinado

Documentación

Servidor WhatsApp MCP

Este es un servidor de Model Context Protocol (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 a individuos o grupos. También puedes enviar archivos multimedia, incluyendo imágenes, videos, documentos y mensajes de audio.

Se conecta a tu cuenta personal de WhatsApp directamente a través de la API web multidispositivo de WhatsApp (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í hay un ejemplo de lo que puedes hacer cuando está conectado a Claude.

WhatsApp MCP

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

Precaución: como con muchos servidores MCP, el WhatsApp MCP está sujeto a la tríada letal. Esto significa que la inyección de proyectos podría llevar a la exfiltración de datos privados.

Instalación

Requisitos previos

  • Go
  • Python 3.6+
  • Aplicación Anthropic Claude Desktop (o Cursor)
  • UV (administrador de paquetes de Python), instala con curl -LsSf https://astral.sh/uv/install.sh | sh
  • FFmpeg (opcional) - Solo necesario para mensajes de audio. Si quieres enviar archivos de audio como mensajes de voz reproducibles de WhatsApp, deben estar en formato Opus .ogg. 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 volver a autenticarte.

  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 que CGO esté 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.

Resumen 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 Model Context Protocol (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: Busca contactos por nombre o número de teléfono
  • list_messages: Recupera mensajes con filtros y contexto opcionales
  • list_chats: Lista los chats disponibles con metadatos
  • get_chat: Obtiene información sobre un chat específico
  • get_direct_chat_by_contact: Encuentra un chat directo con un contacto específico
  • get_contact_chats: Lista todos los chats que involucran a un contacto específico
  • get_last_interaction: Obtiene el mensaje más reciente con un contacto
  • get_message_context: Recupera el contexto alrededor de un mensaje específico
  • send_message: Envía un mensaje de WhatsApp a un número de teléfono o JID de grupo especificado
  • send_file: Envía un archivo (imagen, video, audio sin procesar, documento) a un destinatario especificado
  • send_audio_message: Envía 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: Descarga medios de un mensaje de WhatsApp y obtiene la ruta del archivo local

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 Opus .ogg.
    • 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 se almacenan los metadatos de los medios 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 el 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. El 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 mostrar códigos QR.
  • WhatsApp ya inició 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 que se cargue 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 volver a autenticarte.

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