whatsapp

WhatsApp

Connect a WhatsApp account to your Claude Code with an MCP server.

The MCP server logs into WhatsApp as a linked companion device (via whatsmeow, an unofficial WhatsApp Web client) and provides tools to Claude to reply, react, mark messages read, and search recent history. When someone messages you (or a configured group mentions Claude), the server forwards the message to your Claude Code session.

Inspired by — and modelled on — the official Telegram plugin. The Go bridge is adapted from lharries/whatsapp-mcp (MIT).

⚠️ Caveats

• Unofficial client. whatsmeow is reverse-engineered. WhatsApp may flag or ban accounts that use it. Use a secondary number if that risk matters.
• Re-auth every ~20 days. WhatsApp expires linked-device sessions. You'll need to re-scan the QR when that happens.
• Bridge process must stay running. The MCP server spawns and supervises it; if Claude Code exits, so does the bridge.
• Anyone with access to an allowlisted chat can drive Claude. Lock down with dmPolicy: allowlist. Treat the pairing window as you would handing someone your terminal.
• Lethal trifecta. Claude can search_history and send_message — combined with reading your codebase, that's exfiltration-class exposure. Be deliberate about who's on the allowlist.

Prerequisites

• Bun — the MCP server runs on Bun. Install with curl -fsSL https://bun.sh/install | bash. Make sure ~/.bun/bin is in the PATH of the shell that launches claude, otherwise the MCP server spawn fails silently.
• Go 1.23+ — to build the whatsmeow bridge binary. Only needed at install time; the binary is cached in bridge/bin/. Needs CGO (Linux/macOS work out of the box; Windows needs a C toolchain like MSYS2).
• (optional) qrencode — for in-terminal QR rendering by /whatsapp:login (apt install qrencode / brew install qrencode). Without it, the bridge's bridge.log already contains an ASCII QR you can scan — see step 3 below.
• A spare phone with WhatsApp installed for the linked-device QR scan.

Quick setup

1. Install the plugin.

These are Claude Code commands — run claude to start a session first.

/plugin marketplace add janfabian/claude-whatsapp
/plugin install whatsapp@claude-whatsapp
/reload-plugins

The first launch runs bun install and compiles the bridge binary (requires Go). Subsequent launches reuse it.

2. Relaunch with the channel flag.

The server won't ingest messages without this — exit your session and start a new one:

claude --channels plugin:whatsapp@claude-whatsapp

3. Scan the QR.

The bridge writes the pairing string to ~/.claude/channels/whatsapp/qr.txt and renders the QR as ASCII half-block art to its stdout. Two ways to actually see something scannable:

• With qrencode installed: from your Claude Code session, /whatsapp:login renders an inline UTF-8 QR.
• Without qrencode: the bridge already drew the QR in its log. Open a terminal large enough to fit a 33×33 block grid (~70 columns wide), then:

  tail -n 50 ~/.claude/channels/whatsapp/bridge.log
  

  Scan with WhatsApp → Settings → Linked Devices → Link a Device.

⚠️ The raw string in qr.txt looks like 2@xVTVC…,Ql31…,I+fX…,0Q4A…,9 — that's pairing data, not a URL. Some assistants hallucinate a https://wa.me/settings/linked_devices#… prefix; ignore it. The string is only meaningful when encoded as a QR image.

⚠️ QRs rotate every ~30 seconds. Scan immediately. If the link fails, the QR is most likely already stale — /whatsapp:login checks qr.txt's mtime and the bridge's health endpoint before rendering, so re-run it to force a fresh check. A stale QR silently fails on the phone with no error message.

Once accepted, qr.txt disappears and the bridge is paired. Session lasts ~20 days.

Verifying the bridge is actually alive

The plugin's MCP server spawns the Go bridge as a child process. If the spawn failed (bun/go not in PATH, port conflict, etc.) /whatsapp:login will show a QR that nothing is listening to — and WhatsApp can't link to a dead bridge. Quick sanity check from any terminal:

pgrep -af whatsapp-bridge                                # should print the pid + command
curl -s http://127.0.0.1:8080/api/health                 # should print {"connected":true,"logged_in":<bool>}

If either is empty/fails, the bridge isn't running. Restart your Claude Code session with --channels plugin:whatsapp@claude-whatsapp and check claude --debug for spawn errors.

4. Pair a sender.

Have someone DM your number (or DM it from another device). The bridge replies with a 6-character code and drops the message. In Claude Code: