WhatsApp Claude Plugin

Plugin de canal de WhatsApp para Claude Code. Conecta WhatsApp como un canal nativo a tu sesión de Claude Code: envía/recibe mensajes, transcripción de voz, control de acceso y aprobación remota de herramientas. No necesita claves API, utiliza Baileys para la conectividad con WhatsApp Web.

GitHub

Prueba este MCPPatrocinado

Documentación

Canal de WhatsApp para Claude Code

Impulsa tu sesión de Claude Code desde WhatsApp — tu número personal, sin bots, sin claves de API.

El plugin se conecta a WhatsApp como un dispositivo vinculado (el mismo protocolo que WhatsApp Web, mediante Baileys) y lo expone a Claude Code como un canal MCP. Los mensajes entrantes llegan a tu sesión en tiempo real; Claude responde desde tu propio número, por lo que los destinatarios ven un chat normal. Todo se ejecuta localmente en tu máquina — los mensajes viajan directamente entre WhatsApp y tu sesión, sin servidores de terceros en el medio. Una vez vinculado, sigue funcionando mientras tu teléfono esté apagado; solo la sesión de Claude Code debe permanecer abierta, y las reconexiones nunca requieren volver a vincular.

Publicado en el Mercado oficial de plugins de Anthropic — el primer plugin de canal de WhatsApp construido por la comunidad, revisado y publicado por Anthropic.

Instalación

claude plugin marketplace add Rich627/whatsapp-claude-plugin
claude plugin install whatsapp-channel@whatsapp-claude-plugin
claude --dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin

La bandera --dangerously-load-development-channels es importante: registra el plugin como un canal, de modo que un mensaje entrante de WhatsApp active tu sesión de inmediato. Sin ella, las herramientas aún se cargan, pero nada activa la sesión cuando llegan mensajes — quedan sin responder hasta que tú (o un vigilante) le pidas a Claude que revise. --channels aún no acepta este plugin (no está en la lista de permitidos de vista previa de investigación), por lo que la bandera de desarrollo es actualmente la única forma.

Dentro de la sesión, configura tu número y vincula:

/whatsapp-channel:configure <phone>   # country code + number, no +

Se imprime un código de vinculación en el primer lanzamiento. En tu teléfono: WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo → Vincular con número de teléfono en su lugar → ingresa el código. No se involucra la API de WhatsApp Business, una cuenta de desarrollador de Meta ni una clave de API — se vincula a tu cuenta regular.

Otros clientes MCP (Codex CLI, Gemini CLI, Cursor)

El servidor es un servidor MCP stdio simple, por lo que cualquier cliente MCP puede ejecutarlo. Dos cosas son específicas de Claude Code y vale la pena saberlas antes de comenzar:

Los mensajes entrantes no se envían automáticamente. Activar una sesión con un mensaje entrante usa notifications/claude/channel, una extensión de Claude Code. MCP no tiene un equivalente estándar que llegue al modelo, y otros clientes descartan notificaciones desconocidas en silencio. En otros lugares, el plugin se basa en sondeos: llama a wait_for_messages (espera hasta 40 s el siguiente mensaje) o catch_up / unreplied. Cada resultado de herramienta también lleva un conteo de mensajes sin responder, por lo que un cliente se entera de que hay tráfico en su próxima llamada, sea cual sea esa llamada.
La configuración se hace desde una terminal, no con un comando de barra. /whatsapp-channel:access y similares son habilidades de Claude Code. Usa bun scripts/access.ts en su lugar (consulta Control de acceso desde una terminal).

Registra el servidor con una ruta absoluta — ${CLAUDE_PLUGIN_ROOT} se sustituye solo en Claude Code:

Codex CLI (~/.codex/config.toml)

[mcp_servers.whatsapp]
command = "bun"
args = ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"]
startup_timeout_sec = 30   # default 10 is tight for a first Baileys connect
tool_timeout_sec = 120     # default 60; wait_for_messages parks for up to 40s

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bun",
      "args": ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"],
      "timeout": 600000
    }
  }
}

Cursor (~/.cursor/mcp.json para todos los proyectos, .cursor/mcp.json para uno)

{
  "mcpServers": {
    "whatsapp": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"]
    }
  }
}

Solo un cliente a la vez puede mantener la conexión de WhatsApp: WhatsApp permite una sesión de dispositivo vinculado por cuenta, y dos servidores se expulsarían mutuamente. Un segundo servidor no falla en silencio — permanece activo y sirve una única herramienta whatsapp_unavailable que nombra el proceso que mantiene la conexión.

Control de acceso desde una terminal

Todo lo que hace la habilidad de acceso, sin Claude Code:

bun scripts/access.ts status                 # policy, allowlist, pending codes, groups
bun scripts/access.ts policy pairing         # open the door
bun scripts/access.ts pair <code>            # approve someone who messaged you
bun scripts/access.ts allow <jid>            # add directly
bun scripts/access.ts remove <jid>
bun scripts/access.ts group add <groupJid> [--mention] [--allow jid1,jid2]
bun scripts/access.ts set replyToMode first  # ackReaction, textChunkLimit, chunkMode, mentionPatterns

Aprobar siempre requiere el código específico, incluso cuando solo hay una vinculación pendiente: cualquiera puede crear una entrada pendiente solo con enviar un mensaje a la cuenta, por lo que "aprobar la pendiente" es exactamente lo que parece una solicitud inyectada por un mensaje. Por la misma razón, este es un comando de terminal y deliberadamente no es una herramienta MCP, para que nada que llegue por WhatsApp pueda alcanzarlo.

Características

Mensajería bidireccional. Envía y recibe desde la sesión; las respuestas largas se dividen según los límites de WhatsApp o se envían como adjunto de documento más allá de un umbral configurable.
Menciones con @. reply puede etiquetar a personas para que realmente reciban notificaciones — los ids se aceptan como teléfono, LID o JID completo, y las menciones se adjuntan solo al fragmento que las nombra.
Soporte multimedia completo. Fotos, notas de voz, video, documentos y stickers, en ambas direcciones.
Transcripción de voz. Las notas de voz entrantes se transcriben localmente mediante mlx-whisper (consulta configuración); sin el script, llegan como adjuntos simples.
Control de acceso. Códigos de vinculación, listas de permitidos y políticas por grupo controlan cada mensaje entrante — los desconocidos nunca llegan a tu sesión. Se gestiona mediante /whatsapp-channel:access en Claude Code, o bun scripts/access.ts en cualquier lugar.
Personalidades por grupo. Cada grupo tiene su propio config.md con una personalidad personalizada y memoria de conversación.
Relevo de permisos. Aprueba o deniega las solicitudes de herramientas de Claude desde WhatsApp con una reacción de emoji (👍 / 👎).
Tareas programadas. Una sección ## Cron Jobs en el config.md de un grupo programa tareas recurrentes del lado del servidor.
Recuperación de contexto. Después de un reinicio, la herramienta catch_up reproduce la conversación bidireccional reciente por chat, los conteos sin responder y las tareas abiertas desde tasks.md, para que una sesión nueva retome el trabajo en curso.
Cuentas duales. Ejecuta números personales y de negocios en paralelo con estados y comportamientos separados.
Autodiagnóstico. /whatsapp-channel:doctor verifica el proceso del servidor, el vínculo del dispositivo, el bloqueo de instancia única y la configuración, y luego te guía por las correcciones — sin más adivinanzas sobre por qué se detuvieron las respuestas.

Cómo funciona

WhatsApp (phone) <──Baileys──> MCP Server <──stdio──> Claude Code

El servidor (un solo proceso de Bun) mantiene la conexión del dispositivo vinculado y reenvía los mensajes entrantes a la sesión como notificaciones de canal después de que pasan la puerta de acceso. Claude actúa mediante herramientas MCP — reply, react, edit_message, download_attachment, status, unreplied, catch_up, list_groups. El estado de ejecución (autenticación, listas de permitidos, configuraciones de grupo, bandeja de entrada) vive en ~/.whatsapp-channel/, nunca en el repositorio.

Los mensajes enviados por Claude aparecen como provenientes de tu número de teléfono. Usa un número dedicado si quieres una identidad de bot distinta.

Transcripción de voz (opcional)

Configuración única (Apple Silicon, mlx-whisper):

brew install ffmpeg                      # mlx-whisper uses it to decode audio
python3 -m venv ~/whisper-env
source ~/whisper-env/bin/activate
pip install mlx-whisper
cp scripts/whisper-transcribe.sh ~/whisper-transcribe.sh
chmod +x ~/whisper-transcribe.sh
~/whisper-transcribe.sh path/to/sample.ogg   # optional: test

El script de referencia usa mlx-community/whisper-large-v3-turbo — preciso, rápido, multilingüe. Cambia el modelo en el script si prefieres uno más pequeño.

Solución de problemas

Problema	Solución
El código de vinculación no aparece	Ejecuta `/whatsapp-channel:configure <phone>` primero, luego relanza
Error de desconexión 440	Solo se permite una conexión por estado de autenticación. Mata los procesos obsoletos: `pkill -f "whatsapp.*server"`
La sesión no se activa con mensajes nuevos	Causa más común: se lanzó sin `--dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin`. Las herramientas funcionan, pero los envíos entrantes se descartan (`Channel notifications skipped` en el registro de depuración de MCP) — relanza con la bandera.
Los mensajes no llegan	Error conocido del cliente de Claude Code (#37933). El lado del servidor es correcto, a la espera de la corrección del cliente.
Las respuestas aún se envían, nada llega	Envía un mensaje directo al número conectado además de un mensaje de grupo — si un MD llega mientras los grupos permanecen en silencio, significa que el problema está en la ruta de la clave del remitente del grupo, no en la conexión. `~/.whatsapp-channel/diag.log` registra una línea `inbound upsert` por cada lote que WhatsApp entrega, por lo que distingue "nunca llegó" de "llegó y se descartó". Configura `WHATSAPP_DIAG_DEBUG=1` para el flujo de depuración completo de Baileys.
Autenticación expirada	Ejecuta `/whatsapp-channel:configure reset-auth` y vuelve a vincular

Documentación

La documentación completa está en USAGE.md: control de acceso, las herramientas expuestas al asistente, configuración de cuentas duales, conflictos de sesión y restablecimiento de autenticación.

Contribuciones

Se aceptan problemas y solicitudes de extracción — lee CONTRIBUTING.md antes de abrir una. Reporta problemas de seguridad de forma privada según SECURITY.md.

WhatsApp Claude Plugin

Documentación

Canal de WhatsApp para Claude Code

Instalación

Otros clientes MCP (Codex CLI, Gemini CLI, Cursor)

Control de acceso desde una terminal

Características

Cómo funciona

Transcripción de voz (opcional)

Solución de problemas

Documentación

Contribuciones

Historial de estrellas

Licencia