WhatsApp MCP

Self-host your WhatsApp accounts and connect them to agents through standard MCP. Pair each number with a QR. Read chats, contacts, messages and groups. Send text or attachments from an explicitly selected account, including to yourself and to WhatsApp numbers that are absent from your contacts.

Español · Deployment · Agent connections · Tools · Architecture · Roadmap and migration

This is an independent TypeScript application using Baileys directly. It does not require Evolution API, Redis, PostgreSQL, Chromium, an AI API key or a particular AI provider. One persistent service owns the WhatsApp sockets; many agents connect to it. A small web page handles accounts and QR pairing.

Status: v0.1, experimental. Automated integration tests use a simulated WhatsApp transport. An optional network smoke test verifies that the real transport receives a QR. Actual phone pairing, bidirectional delivery and device restart continuity must be verified on each deployment. Tests of another backend do not establish those results for this one.

Quick start with Docker

Requires Git and Docker Engine with Compose on your own server.

git clone https://github.com/kaizentrick/whatsapp-mcp.git
cd whatsapp-mcp
docker compose up -d --build
docker compose exec whatsapp-mcp cat /data/admin.token

Open http://127.0.0.1:8787 on that machine, paste the owner access key, create an account and select Pair with QR. On the phone choose WhatsApp → Linked devices → Link a device. Repeat for each number. If the server is remote, use an SSH port forward or configure HTTPS as described in deployment.

The access key above is private. The generated keys and SQLite files stay in a persistent Docker volume. Do not remove the volume when upgrading.

For public MCP access, set WA_PUBLIC_URL=https://whatsapp.example.com and put an HTTPS reverse proxy or tunnel in front of port 8787. The MCP endpoint is https://whatsapp.example.com/mcp. The Compose port remains bound to loopback.

Related MCP server: MCP WhatsApp

Run from source

Requires Node.js 24 or newer and npm.

git clone https://github.com/kaizentrick/whatsapp-mcp.git
cd whatsapp-mcp
npm ci
npm run build
export WA_DATA_DIR="$PWD/data"
node dist/cli.js init
node dist/cli.js serve

Open the same web page. Read the private data/admin.token locally to sign in. The default data location without WA_DATA_DIR is $XDG_DATA_HOME/whatsapp-mcp or ~/.local/share/whatsapp-mcp.

Connect an agent

Any agent supporting MCP Streamable HTTP with OAuth or Bearer authentication can use /mcp. Agents supporting stdio can run the included bridge:

WA_SERVER_URL=https://whatsapp.example.com \
WA_CLIENT_TOKEN_FILE=/private/path/client.token \
node /absolute/path/whatsapp-mcp/dist/cli.js stdio

The bridge connects to the running service; it does not open another WhatsApp session. See client examples for Codex and a generic mcpServers configuration. Compatibility depends on each client's supported MCP transports and authentication methods.

Generate a separate credential for each agent, restricted to one account:

node dist/cli.js token:create --account Sales \
  --permissions read,send --days 30 --out /private/path/sales-agent.token

Keep the same WA_DATA_DIR setting used by the service. Without send, an agent cannot send; without manage, it cannot pair, pause or unlink accounts. The owner credential can access all accounts. OAuth consent can reduce granted permissions further. Credentials are revocable.

Features and boundaries

• Multiple isolated accounts, each bound to the first paired phone identity.

• QR rotation and expiry, reconnect backoff, durable Signal credentials and keys.

• Twenty focused tools, pagination, group participant identifiers and PN/LID aliases.

• Text, images, documents and audio; bounded base64 uploads and media downloads.

• Idempotent send requests and explicit handling of uncertain send outcomes.

• OAuth discovery, dynamic registration, PKCE S256 and rotating refresh tokens.

• Private local SQLite storage; credentials, raw messages and OAuth records are encrypted. Searchable text and routing metadata are not encrypted at rest.

• No campaigns, AI models, workflows, billing, CRM or automated replies.

An unsaved contact can receive messages if the number is registered on WhatsApp. A number without a WhatsApp account cannot. History is limited to what WhatsApp synchronizes to the linked device. The service does not promise a complete copy of everything on the phone. Messages are read from stored history without marking them as read. Group receipts retain participant identity.

This uses the unofficial Baileys WhatsApp Web transport. Protocol changes, account restrictions and pairing requirements remain external constraints. This is not the official Meta Business Platform and is not affiliated with WhatsApp or Meta.

Development

npm ci
npm test
npm run check
npm run audit:runtime
docker build -t whatsapp-mcp:local .

CI runs the tests and starts/restarts the non-root container. Tests never send real messages. For an explicit, disposable real-network QR check:

npm run build
node scripts/smoke-qr.mjs

This creates a temporary unpaired session, reports only whether a QR arrived, and removes its temporary state. It never prints the QR payload or sends a message. See acceptance for real-phone verification.

License

Project source is GPL-3.0-only, with third-party components under their respective licenses. See LICENSE and NOTICE. This repository does not copy Evolution API implementation code. Baileys is MIT licensed; the runtime dependency libsignal is GPL-3.0.