whatsapp-connect-mcp

Un servidor MCP de WhatsApp distribuido como un único binario estático de Go. Una descarga, un comando setup, un escaneo de QR — entonces cualquier cliente MCP (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, …) puede leer, buscar y enviar mensajes de WhatsApp, con cada envío saliente protegido por una compuerta impuesta por el servidor.

Esto utiliza un protocolo no oficial. Lea esto antes de emparejar un número que le importe.

whatsapp-connect-mcp se comunica con WhatsApp de la misma manera que WhatsApp Web, a través de whatsmeow — no una API oficial de WhatsApp Business. Meta puede y de hecho banea números que detecta utilizando clientes de terceros en este protocolo, y dichos baneos son ampliamente reportados como permanentes. La compuerta de envío y el limitador de velocidad descritos a continuación reducen la mitad conductual de ese riesgo (envíos masivos accidentales, un modelo descontrolado); no pueden tocar la otra mitad, que es que este cliente es identificable como un cliente de terceros en absoluto. Riesgo de baneo expone lo que la evidencia pública realmente muestra, con fechas. Empareje un número con el que esté dispuesto a perder, no su única línea con su banco o su familia.

Estado: prelanzamiento.

Instalación (dos minutos)

Elija uno:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.ps1 | iex

# Anywhere with Node installed, no separate download step
npx whatsapp-connect-mcp setup

npx whatsapp-connect-mcp serve funciona bien por sí solo, pero para setup prefiera uno de los scripts de instalación anteriores. setup inyecta una ruta absoluta al binario en ejecución en la configuración de cada cliente MCP, y bajo npx esa ruta está dentro del caché de paquetes de npm — borre ese caché y cada configuración de cliente que setup escribió ahora apunta a un binario que ya no existe.

Cada uno de estos descarga el binario de la versión para su sistema operativo/arquitectura y ejecuta setup: muestra un código QR para escanear desde WhatsApp (Dispositivos vinculados → Vincular un dispositivo), luego detecta los clientes MCP instalados y ofrece inyectar una entrada de servidor whatsapp en los que usted elija. Sin cadena de herramientas, sin edición manual de JSON.

setup también pregunta cómo deben conectarse los clientes. stdio (el valor predeterminado) hace que cada cliente inicie su propio proceso de servidor — el más simple, pero solo un cliente o sesión puede estar conectado a la vez, ya que un serve mantiene el bloqueo exclusivo del directorio de datos. http apunta cada cliente seleccionado a un servidor local compartido (http://127.0.0.1:<port>, puerto de su elección, por defecto 2178, autenticado con token de portador) para que varios clientes y sesiones se conecten a la vez — la contrapartida es que usted mismo inicia ese servidor con whatsapp-connect-mcp serve --http 127.0.0.1:<port> y los clientes solo pueden conectarse mientras esté en ejecución.

setup se puede volver a ejecutar en cualquier momento — para emparejar de nuevo, o para añadir un cliente que instaló después.

Pase --full-history para pedirle al teléfono tanta historia como permita el protocolo en lugar de los pocos meses predeterminados. Solo tiene efecto mientras se empareja realmente, por lo que una instalación que ya está emparejada debe remove primero; setup lo dice en lugar de ignorar silenciosamente la bandera. El teléfono sigue decidiendo lo que realmente envía.

Related MCP server: WhatsApp Business API MCP Server

Para qué sirve esto

Las catorce herramientas de lectura son el producto; las diez herramientas de escritura con compuerta son una conveniencia. En la práctica, eso significa:

• Buscar su propio historial. La búsqueda propia de WhatsApp no tiene filtros de fecha y le muestra un resultado sin contexto alrededor. search_messages más get_message_context hacen ambas cosas.

• Ponerse al día. Apunte un modelo a los 400 mensajes que un grupo acumuló mientras usted estaba ausente y pregunte qué pasó.

• Leer sus propios archivos adjuntos. download_media descarga las facturas, recibos y capturas de pantalla que la gente le envió para que un modelo pueda leerlos realmente.

• Encontrar cabos sueltos. get_last_interaction responde '¿quién me escribió a quien nunca respondí?'

• Redactar respuestas. El modelo lo escribe, la compuerta de envío le hace confirmarlo, luego se envía.

• Buscar en WhatsApp junto con todo lo demás. Con servidores MCP de correo, chat o calendario conectados al mismo cliente, '¿me contactó este cliente sobre la factura y dónde?' se convierte en una pregunta en lugar de tres búsquedas separadas. Para cualquiera cuya correspondencia real viva en WhatsApp, esta es la razón para ejecutarlo.

Para qué no usarlo

No construya un bot de soporte, una herramienta de divulgación o un auto-respondedor sobre esto. Enviar mensajes a personas que nunca le escribieron primero, en volumen, es el comportamiento que más consistentemente se reporta como causante de baneos de números (ver Riesgo de baneo) — y es precisamente el caso de uso para el que Meta vende la API de WhatsApp Business. Esta es una herramienta personal para sus propios mensajes. Apúntela a clientes y perderá el número.

Lo que ofrece a su cliente MCP

Veinticuatro herramientas: catorce de solo lectura, diez con compuerta, descritas a continuación.

Lectura / búsqueda (sin compuerta)

Hasta dónde llega cualquiera de estos lo decide el teléfono emparejado, no este servidor. 'Buscar todo mi historial' puede resultar ser 'buscar los últimos meses' — consulte Limitaciones.

Envío (con compuerta — ver más abajo)

Cada resultado de herramienta construido a partir de datos de WhatsApp — mensajes, nombres, contactos, pies de foto — está envuelto en un banner explícito de datos no confiables. Trátelo como datos que un cliente MCP le está mostrando, nunca como instrucciones que el modelo deba seguir: nada que llegue a través de WhatsApp puede decirle a su asistente qué hacer.

La compuerta de envío

Esta es la parte que verygoodplugins/whatsapp-mcp no tiene. Cada acción saliente — texto, multimedia, nota de voz, reacción, edición, eliminación, encuesta, bloqueo, desbloqueo o confirmación de lectura — pasa por un único camino, impuesto por el servidor, no indicando al modelo que 'tenga cuidado':

1. Borrador primero. Llame a una herramienta de envío para un destinatario que aún no ha confiado, y no se envía nada. Obtiene una vista previa (el destinatario resuelto a un nombre + JID, y el contenido saliente exacto) y un draft_token.

2. Confirme para comprometer. Vuelva a emitir la llamada idéntica con ese draft_token y se envía. Los borradores expiran después de 5 minutos; una diferencia de un byte en el contenido reenviado invalida el token.

3. Confíe, deliberadamente. whatsapp-connect-mcp trust --add <jid> marca un contacto o grupo como confiable, por lo que los envíos a él se comprometen en la primera llamada en lugar de hacer un borrador. Este es un interruptor solo de CLI — ninguna herramienta MCP puede otorgar confianza, por lo que un modelo no puede sortear el paso de borrador confiando. Un proceso serve en ejecución lee la lista de confianza una vez al inicio, por lo que un cambio tiene efecto la próxima vez que serve se inicie, no inmediatamente. Para la sesión en ejecución hay una concesión más ligera: whatsapp-connect-mcp trust --session --add <jid> eleva a un destinatario solo durante la vida del proceso serve actual — tiene efecto inmediatamente, nunca se escribe en config.json, y se borra automáticamente la próxima vez que serve se inicie. Úselo cuando esté redactando activamente un hilo con una persona o grupo y ya haya confirmado los primeros envíos manualmente; reduce el ciclo de borrador y confirmación para ese destinatario sin otorgar nada permanente. Al igual que la confianza persistente, es solo de CLI (ninguna herramienta MCP puede otorgarla), y bloquear/desbloquear aún genera un borrador en cada llamada independientemente.

4. Límite de velocidad, siempre. Cada envío — borrador, confiado, lo que sea — consume un token de un limitador de velocidad compartido entre las cinco herramientas de envío. El intervalo tiene un piso duro de 5 segundos que ninguna configuración puede reducir. Un compromiso limitado por velocidad deja el borrador válido; reintente la misma llamada con el mismo token una vez que se despeje el límite.

mark_read es la única excepción al borrador: una confirmación de lectura no es contenido creado, por lo que siempre se envía en la primera llamada (aún limitado por velocidad, aún compuertado).

Qué archivos puede adjuntar un envío

La compuerta anterior autoriza a un destinatario. No dice nada sobre el archivo que nombra un envío, por lo que por sí solo permitiría que un modelo manipulado adjunte cualquier cosa que este programa pueda leer — una clave SSH, un almacén de contraseñas — a un destinatario en el que ya había confiado.

Por lo tanto, los archivos salientes se limitan a una lista de directorios permitidos. El valor predeterminado es uno dedicado, creado en la primera ejecución:

Mueva un archivo allí antes de enviarlo, o amplíe la lista configurando media_roots en config.json con rutas de directorio absolutas:

{ "media_roots": ["/home/you/Pictures", "/home/you/Documents"] }

Las rutas se resuelven antes de verificarse, por lo que un enlace simbólico dentro de un directorio permitido se juzga por dónde lleva realmente, no por dónde está. Un envío que nombre un archivo fuera de la lista se rechaza en la primera llamada — antes de que se cree un borrador y antes de que cueste un token de límite de velocidad — y el rechazo no nombra ninguna ruta, como cualquier otro error que devuelve este servidor.

Comparación con verygoodplugins/whatsapp-mcp

Riesgo de prohibición

Meta detecta clientes de terceros de dos formas independientes, y solo una de ellas es comportamiento.

1. El cliente es identificable. Un dispositivo vinculado se anuncia a sí mismo cuando se registra. Los valores predeterminados de whatsmeow anuncian una cadena de SO de whatsmeow con un tipo de plataforma desconocido, que es distinguible de un cliente oficial con solo leer la carga útil de vinculación. Este proyecto sobrescribe eso y anuncia una identidad de navegador Chrome en su lugar (internal/bridge/bridge.go), que también es lo que su teléfono muestra para este dispositivo en Dispositivos vinculados.

No confundas esa anulación con una solución. Derrota la versión más trivial de la comprobación, no el problema subyacente. serve y setup actualizan la versión reportada de WhatsApp Web antes de conectarse, por lo que la versión y el hash de compilación derivado de ella rastrean una versión real en lugar de la que se incluyó en el momento de la compilación, pero el agente de usuario aún lleva los campos de operador y fabricante predeterminados de whatsmeow, y la sesión se comporta en la red como whatsmeow, no como Chrome. Los usuarios de whatsapp-web.js — que utiliza un navegador Chrome real con una huella digital genuina — recibieron las mismas advertencias descritas a continuación, lo que sugiere que la identidad anunciada nunca fue la señal decisiva. Cambiarla tampoco hace nada por una sesión que ya está emparejada: la identidad se envía al emparejar, por lo que una sesión existente conserva con la que se registró hasta que la emparejes de nuevo.

2. Comportamiento. Desencadenantes reportados, aproximadamente por la frecuencia con la que aparecen: enviar mensajes a personas que nunca te enviaron un mensaje primero, alta velocidad de envío, volumen poco después del emparejamiento, el mismo mensaje enviado repetidamente, publicaciones de Estado automatizadas y bucles de reconexión ruidosos.

La parte incómoda es que la evidencia pública apunta a (1) como el factor dominante. En whatsmeow#810 — la oleada de mayo de 2025 de "tu cuenta puede estar en riesgo", cerrada como no planificado en julio de 2026 — los usuarios reportan la advertencia en cuentas que estaban inactivas y simplemente conectadas, sin haber enviado nunca un mensaje, y en cuentas que habían estado desconectadas durante semanas. Los usuarios de whatsapp-web.js, una implementación completamente diferente, también la recibieron. Un mantenedor de Baileys en ese mismo hilo argumenta lo contrario, que es "principalmente un problema de comportamiento". Nadie estableció cuál, y el hilo se cerró sin respuesta.

Por lo tanto: el límite de envío y el limitador de velocidad aquí son mitigaciones reales para (2) y no hacen nada para (1). Según la evidencia disponible, comportarse bien afecta cuándo llega tu turno, no si llega.

Informes que vale la pena leer antes de emparejar, con fecha para que puedas juzgar qué tan actualizados están:

Trata las estadísticas de prohibiciones de blogs de proveedores — "el 68% de las empresas prohibidas en 12 meses", "un umbral de no respuesta de 30 días continuos" — como marketing sin fuente de revendedores pagados de API de Negocios. Ninguna fuente primaria las respalda, y ninguna de las dos cifras aparece en este documento por esa razón.

Limitaciones (expresadas claramente)

• Tu número puede ser prohibido, y este proyecto no puede evitarlo. Consulta Riesgo de prohibición. Esta es la limitación que más importa.

• La profundidad del historial la decide el teléfono. Como cualquier cliente de WhatsApp Web, el teléfono emparejado controla cuánto historial de chat se sincroniza con este servidor. No hay ninguna configuración aquí que obtenga más de lo que el teléfono entrega. setup --full-history solicita tanto como el protocolo permite en lugar de los pocos meses predeterminados, pero es una solicitud, no una configuración — y solo se aplica al emparejar. Para una instalación que ya está emparejada, la herramienta fetch_older_messages le pide al teléfono más de un solo chat sin volver a emparejar. Ambas son solicitudes que el teléfono puede responder con menos, o nada; ninguna recupera mensajes que el propio teléfono haya eliminado.

• Las notas de voz necesitan entrada Ogg Opus. send_voice_note no realiza transcodificación. Si tu audio fuente no es ya .ogg/Opus, conviértelo primero (ej. ffmpeg -i in.mp3 -c:a libopus out.ogg).

• Sin llamadas salientes. El historial de llamadas es legible; no se admite iniciar una llamada.

• Un número emparejado por instalación. No se admite multi-cuenta en v1.

• whatsmeow rastrea los cambios del protocolo de WhatsApp, no al revés. Un cambio del lado de WhatsApp puede romper el emparejamiento o el envío hasta que whatsmeow (y, a su vez, este proyecto) se ponga al día.

Datos y privacidad

Todo — claves de sesión, mensajes, medios, contactos, registro de llamadas — reside en una base de datos SQLite local en el directorio de datos de este programa. Nada sobre tus mensajes, contactos o medios es enviado a ningún lado por este servidor.

Existen exactamente dos llamadas de red salientes más allá de la propia conexión de WhatsApp. Ambas son de mejor esfuerzo, ambas expiran después de 2 segundos, y ninguna lleva contenido de mensaje, un JID, un número de teléfono o ninguna credencial de sesión:

• doctor/check pregunta a la API de versiones públicas de GitHub si existe una versión más reciente de este programa. Nunca bloquea ni falla la comprobación cuando GitHub es inalcanzable.

• serve y setup obtienen la versión actual del cliente de WhatsApp Web de web.whatsapp.com antes de conectarse, para que la versión que reporta este cliente rastree una versión real en lugar de la que se incluyó en el momento de la compilación. Un fallo se reporta y se ignora; una versión desactualizada aún se conecta.

El directorio de datos:

Diagnóstico

whatsapp-connect-mcp check

Ejecuta las mismas comprobaciones que expone la herramienta MCP doctor: estado de emparejamiento/conexión de la sesión, actividad del flujo de eventos (una sesión conectada que no ha recibido eventos de WhatsApp durante más de 30 minutos recibe una advertencia — el estado en el que el socket parece saludable pero la ingesta se ha detenido silenciosamente), integridad de la base de datos de mensajes, configuraciones de cliente MCP inyectadas, permisos del directorio de datos (POSIX) y la comprobación de versión anterior. Cada hallazgo está sanitizado — ningún JID, número de teléfono, contenido de mensaje o ruta de sistema de archivos aparece nunca en una línea de estado; una configuración de cliente rota se nombra por el nombre del cliente, nunca por su ruta en el disco.

Otros comandos

whatsapp-connect-mcp setup [--full-history]  # pair (again) and configure MCP clients
whatsapp-connect-mcp status                  # pairing state, row counts, injected clients
whatsapp-connect-mcp clients [--remove]      # list or uninject MCP client entries
whatsapp-connect-mcp trust [--session] [--add jid|--remove jid|--list]
whatsapp-connect-mcp serve [--http addr]     # run the MCP server directly (stdio by default)

--http requiere un token de portador y un Host de bucle local. En el primer uso genera un token de 256 bits, lo escribe en .http-token en el directorio de datos (solo propietario), y lo imprime una vez — ponlo en el encabezado Authorization: Bearer <token> de tu cliente. Cada solicitud también debe dirigirse a un Host de bucle local (localhost, 127.0.0.1, [::1]), lo que bloquea que una página web en tu navegador llegue al servidor al reenlazar DNS a una dirección de bucle local. Vincula 127.0.0.1 de todos modos: el token protege contra llegar al puerto, pero vincular una interfaz pública lo expone a toda tu red, y si es necesario, pon tu propio control de acceso (un proxy inverso, una VPN, una regla de cortafuegos) delante.

Desinstalar / restablecer

• whatsapp-connect-mcp remove elimina la sesión local de WhatsApp (desempareja este servidor de ella localmente — el próximo setup requerirá emparejar de nuevo). Esto es solo local: no notifica a los servidores de WhatsApp, por lo que tu teléfono seguirá mostrando este dispositivo como vinculado en Dispositivos Vinculados hasta que lo desvincules tú mismo allí. Solicita un sí escrito antes de hacer cualquier cosa.

• whatsapp-connect-mcp reset hace todo lo que hace remove, más elimina los mensajes, medios y configuraciones almacenados — un borrado completo a una instalación nueva. También solicita un sí escrito.

• whatsapp-connect-mcp clients --remove desinyecta la entrada de este programa de cualquier configuración de cliente MCP a la que se haya añadido, sin tocar la sesión emparejada.

• Para eliminar el binario en sí, bórralo de donde lo puso el instalador (~/.local/bin, %LOCALAPPDATA%\Programs\whatsapp-connect-mcp, o donde npx lo haya almacenado en caché) y elimina el directorio de datos listado anteriormente.

Licencia

MIT — consulta LICENSE.