WhatsApp MCP Server

A local stdio-only MCP server for a personal WhatsApp account using WhatsApp Web QR pairing. It provides chat and media reading plus safe opt-in text and media sending. Outbound tools are disabled unless explicitly enabled and limited to an allowlisted set of chats.

Risk: this uses an unofficial WhatsApp Web library. WhatsApp may change its protocol or restrict accounts that use unofficial clients. Use only with your own account, keep session state private, and prefer a separate account for experimentation.

Install

npm install
cp .env.example .env
npm run build

Set WHATSAPP_ALLOWLIST in .env to comma-separated WhatsApp JIDs. It is required for send_message and send_media; read tools remain available with an empty allowlist. Keep outbound files in WHATSAPP_OUTBOUND_MEDIA_DIRS (default: ./outbox).

Related MCP server: whatsapp-mcp

Pair

npm start

On first launch the server writes whatsapp-qr.png locally with mode 0600. Scan it from WhatsApp: Linked devices → Link a device. The local auth directory and media directories are created with mode 0700.

The process speaks MCP over stdin/stdout. Status and errors use stderr only. Do not expose this process behind HTTP or a network socket.

MCP tools

• connection_status — pairing/connection state and local QR location

• list_chats — cached chats

• search_messages — text search over the local session cache

• read_messages — recent cached messages for an allowlisted chat

• download_media — save a cached allowlisted message attachment locally

• fetch_all_chats — list every chat in the local session cache

• fetch_message_history — page older messages for an allowlisted chat via Baileys fetchMessageHistory

• send_message — send text to an allowlisted chat (requires WHATSAPP_SENDING_ENABLED=true)

• send_media — send an image, video, audio, document, or sticker from an approved local file (requires WHATSAPP_SENDING_ENABLED=true)

The cache starts filling after WhatsApp history/message events arrive. It is intentionally not a full archive. fetch_message_history can pull older messages on demand, but only while the WhatsApp socket is connected.

MCP client configuration

{
  "mcpServers": {
    "whatsapp-local": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_ALLOWLIST": "1234567890@s.whatsapp.net",
        "WHATSAPP_SENDING_ENABLED": "true",
        "WHATSAPP_OUTBOUND_MEDIA_DIRS": "/absolute/path/to/whatsapp-mcp-server/outbox"
      }
    }
  }
}

Safety controls

• Stdio transport only; no HTTP listener.

• Sending is disabled by default. send_message and send_media require WHATSAPP_SENDING_ENABLED=true and a non-empty WHATSAPP_ALLOWLIST.

• Send tools are gated at call time, so a config typo cannot silently enable them.

• Outbound media must resolve to a regular file within WHATSAPP_OUTBOUND_MEDIA_DIRS and stay below WHATSAPP_MAX_OUTBOUND_MEDIA_BYTES (64 MiB default).

• Outbound sends have a separate rate limit (default: 10/minute) independent of read limits.

• Input validation via Zod on every tool.

• Per-process read rate limit (default: 30 tool calls/minute).

• Result caps (default: 50) and local allowlist support.

• Auth files, QR image, downloaded media, outbound files, .env, build output, and logs are gitignored.

• Sensitive files/directories are written with 0600/0700 modes where created by this service.

Verify

npm run check
npm test

License

MIT. See LICENSE.

Viewing the QR code

The QR image is written to the local whatsapp-qr.png path. Attach or upload that image in your MCP client UI after launching the server. The QR expires quickly; call connection_status after scanning to confirm the connection state is connected.

Whatsapp-Mcp