whatsapp-mcp-kit

Connect Claude (Claude Code / Claude Desktop / Codex — any MCP client) to a WhatsApp account so it can read your chats and send messages. The server already exists and is good; what nobody ships is the linking procedure. Ours took an evening of broken iterations and a re-scan loop; with this kit it should take you ~20 minutes.

Built and battle-tested at Palo Alto AI Research Lab — our Claude fleet has been reading WhatsApp through exactly this setup since June 2026.

⚠️ Read docs/SECURITY.md first. Baileys is an unofficial WhatsApp client; upstream recommends a dedicated number, not your personal one. We linked a main number knowingly and accept the ban risk. That should be a decision, not an accident.

What you get

1. A working setup path on top of the upstream server @sjawhar/whatsapp-mcp (Node/Baileys, security-hardened fork of karlfoster/whatsapp-mcp-2.0; 17 tools — list/search chats, messages, contacts, send text & files, download media, transcribe voice notes).
2. PROMPT.md — a copy-paste prompt you hand to Claude Code or Codex; it performs the installation and walks you through the QR scan, gotchas included.
3. pair/wa_qr_live.py — the piece that made linking actually work: it keeps the stdio server alive, scrapes the raw QR string out of its log, renders a PNG and serves a live localhost page that refreshes the code by itself. Plus a 27-check regression test that needs no phone, no network and no server installed.
4. Patches we run in production, pinned to upstream npm v2.4.0 (git apply --check proven on a fresh npm pack unpack):
   • patches/0001-qr-raw-to-stderr.patch — print the raw QR string, always. Upstream only emits terminal ASCII art (and the raw string solely in a .catch() fallback), and that art is unscannable mosaic in most Windows console fonts. Without this patch there is nothing to render a PNG from.
   • patches/0002-group-subject-resolve.patch — real group names. db.getChat always fills a <digits> (group) placeholder, so resolveChatName never fires and every group shows up as a number. Cost us ~70 unnamed groups.
5. docs/GOTCHAS.md — every trap we paid hours for, with dates.
6. docs/SECURITY.md — a WhatsApp MCP is your whole WhatsApp. Read before linking.

Quickstart (manual)

# 0. get the kit (patches/ and pair/ must sit together on disk)
git clone https://github.com/tonydzi/whatsapp-mcp-kit ~/whatsapp-mcp-kit

# 1. install the server (Node >= 18)
npm i -g @sjawhar/whatsapp-mcp

# 2. apply the kit patches to the installed package
#    (the folder is not a git repo -- git apply patches a plain working tree just fine)
cd "$(npm root -g)/@sjawhar/whatsapp-mcp"
git apply ~/whatsapp-mcp-kit/patches/0001-qr-raw-to-stderr.patch
git apply ~/whatsapp-mcp-kit/patches/0002-group-subject-resolve.patch

# 3. link the phone: live QR page on http://127.0.0.1:8799
pip install qrcode pillow
python ~/whatsapp-mcp-kit/pair/wa_qr_live.py

# 4. register in Claude Code
claude mcp add whatsapp --scope user -- node "$(npm root -g)/@sjawhar/whatsapp-mcp/dist/index.js"