WhatsApp MCP

A Baileys-based MCP server for WhatsApp: a persistent connection that maintains a local message store, exposing tools to list, read, search, and send — so an MCP client (Claude, or an agent like garvis) can work with your WhatsApp messages.

Unlike scraping WhatsApp Web in a browser, this speaks WhatsApp's WebSocket multi-device protocol directly: no browser, no DOM selectors, no headless crashes.

Status

🚧 Early/local development. Not yet published.

Related MCP server: whatsapp-connect-mcp

How it works

WhatsApp's multi-device protocol is event-driven and only delivers messages while you're connected, so this runs as a resident connection + local store:

• Daemon — holds the WebSocket connection, persists incoming messages to a local SQLite store, and auto-reconnects. Auth is a paired session (useMultiFileAuthState), created once via QR / pairing code.

• MCP server — reads the store and sends via the socket, exposing the tools.

One paired session = one socket, so the two coordinate instead of fighting over it: while the daemon runs, it is the sole socket owner and serves a loopback IPC (daemon.json next to the store: pid + random port + per-run token, 127.0.0.1 only). The MCP server auto-detects it and proxies socket ops (send/delete/status) through it; reads always hit the shared WAL-mode SQLite store directly. With no daemon running, the MCP server opens the socket itself, as before. If the daemon dies mid-session the proxy flags itself dead and the next tool call falls back to a self-owned socket.

Run the daemon persistently (macOS)

launchd does not expand ~ or $HOME, so build the LaunchAgent from the template — it needs absolute paths for your machine:

sed -e "s#__NODE__#$(command -v node)#" \
    -e "s#__REPO__#$PWD#" \
    -e "s#__HOME__#$HOME#" \
    com.whatsapp-mcp.daemon.plist.example \
    > ~/Library/LaunchAgents/com.whatsapp-mcp.daemon.plist
launchctl load -w ~/Library/LaunchAgents/com.whatsapp-mcp.daemon.plist   # start + at login
tail -f ~/Library/Logs/whatsapp-mcp-daemon.log                           # watch it
launchctl unload -w ~/Library/LaunchAgents/com.whatsapp-mcp.daemon.plist # stop

A resident daemon means the store keeps filling 24/7 (better history than the MCP server's lazy on-demand connection) and MCP clients get instant reads.

History reflects what has been synced since you connected (on-connect sync + live events), not your entire WhatsApp past.

⚠️ Important caveats

• Unofficial. This uses a reverse-engineered protocol library and is against WhatsApp's Terms of Service. Accounts can be banned, especially for high-volume or spammy automation. Use a number you can afford to lose; for sanctioned automation use the WhatsApp Business Cloud API instead.

• Personal use only, low volume, people you know.

• Deletion is guarded, never automatic: it requires an explicit confirm: true (otherwise the tool only previews), defaults to delete-for-me, and only allows delete-for-everyone on your own messages. See the security model.

Tools

All tools are prefixed whatsapp_ to avoid name collisions with other MCP servers.

Delete semantics. "For me" clears the message/chat from your devices only. "For everyone" (messages only, your own only) revokes it for the recipient and leaves a visible "this message was deleted" marker. Both require confirm: true; without it the tool returns a preview and does nothing. Deletes are applied to the local store optimistically; a long-running daemon may re-sync a deleted-for-me item if WhatsApp re-delivers it.

License

GNU AGPL-3.0-or-later. Note the network-use clause: running a modified version as a network service obligates you to offer its source to users.