waxum-mcp

Servidor MCP para WhatsApp, respaldado por la pasarela de API REST waxum. Expone herramientas de envío/lectura/medios a cualquier cliente MCP (Claude Desktop, Claude Code, etc.) a través de stdio.

Requiere waxum >= 0.11.5 (necesita GET /messages/chat/{chat_jid}).

El emparejamiento de sesión (vinculación por QR / número de teléfono) no forma parte de este servidor: empareja la sesión directamente contra waxum primero (su propia consola o POST /sessions/{id}/pair), y luego apunta este servidor a esa sesión ya emparejada.

Herramientas

Related MCP server: mcp-wacli

Configuración

Dos formas de apuntar este servidor a waxum, elegidas por WAXUM_MODE (o auto-detectadas: client si WAXUM_BASE_URL está definido, si no spawn).

Modo cliente — waxum ya ejecutándose en otro lugar

WAXUM_MODE=client
WAXUM_BASE_URL=http://localhost:3451
WAXUM_TOKEN=<superadmin token or a session token>
WAXUM_SESSION_ID=<the session to operate on>
WAXUM_MEDIA_DIR=./media   # optional, default ./media

Modo spawn — este servidor gestiona el proceso de waxum

WAXUM_MODE=spawn
WAXUM_BINARY_PATH=/path/to/waxum
WAXUM_WORKDIR=/path/to/waxum/data   # optional, default: binary's directory
WAXUM_PORT=3451                     # optional, default 3451
WAXUM_TOKEN=<superadmin token>      # optional, a random one is generated if unset
WAXUM_SESSION_ID=<the session to operate on>
WAXUM_DATABASE_URL=sqlite:///data/waxum.db # optional

En el modo spawn, el token se convierte en la variable de entorno SUPERADMIN_TOKEN del proceso generado — la credencial de arranque propia de waxum — por lo que no es necesario acuñar ningún token de antemano. La salida estándar y el error estándar del proceso hijo se reenvían al error estándar de este servidor (nunca a la salida estándar, que está reservada para el canal de protocolo MCP).

El modo spawn usa SQLite por defecto en <WAXUM_WORKDIR>/waxum.db, manteniendo el servidor MCP sin configuración y seguro ante reinicios. Establece WAXUM_DATABASE_URL a una ruta sqlite:// explícita, una URL de PostgreSQL o una URL de MySQL cuando sea necesario.

Desarrollo

npm install
npm run dev     # run directly with tsx
npm run build   # compile to dist/
npm start       # run the compiled build