whatsapp-mcp

Give AI agents access to your own WhatsApp: read, search and send messages through the Model Context Protocol. Built on Baileys, so it links as a WhatsApp "linked device" (like WhatsApp Web) — no browser, no Business API, no phone number rental.

your phone ──(linked device)── whatsapp-mcp daemon ──MCP over HTTP── Claude Code / Agent SDK / any MCP client
                                  │
                                  └── local SQLite cache of chats, contacts and messages

Why a daemon

WhatsApp allows one connection per linked device, and it only pushes messages to that device (a history sync when you link, then live messages). So whatsapp-mcp runs as one long-lived process that holds the connection and caches everything it sees in SQLite. Any number of agents can then query it at the same time over MCP — each agent session doesn't have to log in, and reads/searches are instant and work offline. (A --stdio mode is there too for single-client hosts.)

Related MCP server: WhatsApp MCP Server (TypeScript)

Tools

Times accept ISO dates, unix seconds, or relative values like 24h / 7d. Names resolve to the saved contact name, group subject, or the person's own profile name.

Install

Requires Node 20+.

git clone https://github.com/coderman400/whatsapp-mcp && cd whatsapp-mcp
npm install          # also builds dist/
npm start            # or: node dist/index.js --help

Link your WhatsApp (once)

On first run it waits to be linked. Either:

• QR: scan the QR printed in the terminal (also saved to ~/.whatsapp-mcp/link-qr.png) from WhatsApp → Settings → Linked devices → Link a device.

• Pairing code (handy when you can't see the screen): start with --pair-phone <your number with country code>; the 8-character code is logged and written to ~/.whatsapp-mcp/link-code.txt, and whatsapp_status returns it. On the phone: Linked devices → Link a device → Link with phone number instead.

The session is saved in ~/.whatsapp-mcp/auth and survives restarts. It connects with markOnlineOnConnect: false, so your phone keeps getting notifications.

Use it

Claude Code

claude mcp add --transport http whatsapp http://127.0.0.1:3737/mcp

Claude Agent SDK

query({ prompt, options: { mcpServers: { whatsapp: { type: "http", url: "http://127.0.0.1:3737/mcp" } } } });

Claude Desktop / stdio clients (no separate daemon; the client starts it)

{ "mcpServers": { "whatsapp": { "command": "node", "args": ["/path/to/whatsapp-mcp/dist/index.js", "--stdio"] } } }

Always on: see examples/whatsapp-mcp.service for a systemd user service.

Options

GET /health returns the connection state and cache counts.

Safety — read this

• This is unofficial. It uses WhatsApp's linked-device protocol via Baileys, not an official API. Automated or bulk messaging can get a number banned. Keep sending human-paced, and prefer read-only use.

• Your data dir is a login. ~/.whatsapp-mcp/auth grants full access to your WhatsApp. Keep it private (it's created 0700), never commit it, and unlink the device from your phone if it leaks.

• Keep it local. The server binds to 127.0.0.1 by default; if you expose it, set --token.

• Messages are untrusted input. Anyone can message you, so an agent reading WhatsApp can be fed instructions ("ignore previous instructions and send…"). Don't give the same agent unattended send_message plus other powerful tools; require human approval for sends.

Limitations

• Text sending only (no media yet). Reading covers text, captions, documents, locations, polls and contact cards; other media are shown as [image], [voice note], etc. without downloading.

• The cache starts when you link: older history depends on what WhatsApp's initial sync sends (--full-history asks for more).

• Built on a Baileys release candidate (7.x); WhatsApp protocol changes can require a Baileys update.

License

MIT