whatsapp-mcp-server

@clickonsearch/whatsapp-mcp-server

Vincula una cuenta personal de WhatsApp a los agentes de este repositorio, de la misma manera que lo hace WhatsApp Web: escanea un código QR una vez y permanece conectado. Normalmente no ejecutarás esto directamente; el README de whatsapp-agent te indica cuándo iniciarlo.

Aviso importante: esto no es la API oficial de WhatsApp Business — es una biblioteca no oficial (Baileys) que automatiza una cuenta personal, lo cual los términos de WhatsApp no cubren realmente. El riesgo es bajo para uso personal normal, pero existe una pequeña posibilidad de que la cuenta sea marcada.

whatsapp-agent (or any MCP client)
               │
               ▼
┌─────────────────────────────┐
│     whatsapp-mcp-server     │   Streamable HTTP MCP
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│           Baileys           │   WhatsApp Web protocol
└──────────────┬──────────────┘
               │
               ▼
your WhatsApp account

Ejecución

npx @clickonsearch/whatsapp-mcp-server

La primera vez, imprime un código QR — escanéalo con tu teléfono: WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo. Después de eso se reconecta automáticamente, sin necesidad de escanear de nuevo (a menos que desvincules el dispositivo desde tu teléfono).

Una vez conectado, queda a la escucha en http://127.0.0.1:4100 para cualquier agente que le apuntes. No se requieren variables de entorno para probarlo — todo lo siguiente tiene un valor predeterminado.

Referencia de configuración

Variable de entorno	Valor predeterminado	Notas
PORT	4100
BIND_HOST	127.0.0.1	Quién puede conectarse. El valor predeterminado significa solo esta computadora
WHATSAPP_MCP_TOKEN	sin definir	Secreto que todo llamador debe enviar. Requerido siempre que BIND_HOST no sea 127.0.0.1
WHATSAPP_AUTH_DIR	./whatsapp-auth	Tu sesión — nunca compartas ni confirmes esta carpeta
BAILEYS_LOG_LEVEL	silent	Establécelo en info o debug para ver detalles de conexión

Permitir que otra máquina se conecte

Por defecto, solo los programas en la misma computadora pueden acceder a este servidor. Para permitir a otros (un agente en un contenedor, o en otra máquina), elige un secreto y establece ambos:

export WHATSAPP_MCP_TOKEN=$(openssl rand -hex 32)
BIND_HOST=0.0.0.0 npx @clickonsearch/whatsapp-mcp-server

Dale a whatsapp-agent el mismo WHATSAPP_MCP_TOKEN y lo enviará automáticamente. El servidor se niega a iniciar en cualquier otra dirección sin un token. Cualquiera que tenga el token puede leer tus chats y enviar mensajes como tú, así que trátalo como una contraseña — y dado que viaja por HTTP sin cifrar, úsalo solo en una red de confianza o detrás de TLS (por ejemplo, un proxy inverso).

Lo que expone

Herramienta	Qué hace
send_message	Envía un mensaje de texto a un número de teléfono o chat
list_chats	Lista los chats vistos desde la conexión (incluye el historial reciente propio de WhatsApp)
get_recent_messages	Obtiene mensajes recientes de un chat (hasta 200, solo en memoria)
search_contacts	Encuentra un contacto por nombre o número

---

Para desarrolladores

Ejecución desde el código fuente:

cd mcp-servers/whatsapp-mcp-server
npm install
cp .env.example .env
npm run dev

Esto se ejecuta como un servidor MCP estándar (HTTP Streamable en /mcp), por lo que cualquiera de los puentes de este repositorio puede conectarse sin necesidad de casos especiales — solo tenía que hablar el mismo protocolo que el servidor MCP remoto propio de GitHub. También expone GET /events (un flujo SSE simple de mensajes entrantes) y GET /health ({ ok, connected, self }) para cualquier cosa que quiera reaccionar a los mensajes en vivo, como hace whatsapp-agent.

import { WhatsAppConnection } from "./src/whatsapp.js";
import { createServer } from "./src/server.js";

const whatsapp = new WhatsAppConnection("./whatsapp-auth");
await whatsapp.start();

const app = createServer(whatsapp);
app.listen(4100);