Skip to content

About

Link WhatsApp to Claude (or any MCP client) in ~20 minutes: a live self-refreshing QR page that makes pairing actually work, production patches, and 12 field gotchas. On top of @sjawhar/whatsapp-mcp.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Repository files navigation

whatsapp-mcp-kit

A setup kit that lets an AI assistant (Claude Code, Codex or any MCP client) read your WhatsApp chats and send messages, using your own account.

Who it's for: people who want their AI assistant to work with WhatsApp. What you get: WhatsApp linked to your AI tools through one small local service, plus ready prompts so an agent does the setup.

Account risk, read first: this uses an unofficial WhatsApp client (Baileys). WhatsApp can restrict accounts that use such clients, so a separate number is safest. Your assistant will also see the messages you let it read.

Quick start

  1. Open Claude Code or Codex in an empty folder on the machine that should read WhatsApp.
  2. Paste the block from PROMPT.md (Russian versions: Claude Code, Codex). Read it first: the agent checks what you already have, explains the risk once, installs one shared local service and opens a QR page.
  3. On your phone: WhatsApp > Settings > Linked devices > Link a device, scan the page.

Done when: you send yourself a fresh test word in WhatsApp and the agent reads that exact word back.

Want an AI agent to do it for you? Paste this to Claude Code / Codex / Cursor: "Read the 'For AI agents' section of https://github.com/tonydzi/whatsapp-mcp-kit and set it up for me."

For AI agents

Preconditions

  • The ready-made prompt for you is PROMPT.md (English); Russian: PROMPT-CLAUDE.ru.md, PROMPT-CODEX.ru.md. The full runbook is README.ru.md (Russian). Read the runbook and the prompt from the same revision before acting.
  • Tools: node (a supported LTS), npm, git, Python 3. Windows, macOS or Linux.
  • Account: the human's own WhatsApp on their phone. Only they can scan the QR.
  • Ask the human: which WhatsApp account to link (a separate number is recommended) and whether they accept the account-restriction risk; this is asked once.
  • First do a read-only inventory: existing WhatsApp MCP definitions in both clients (claude mcp list, codex mcp list), running processes, existing data folder, listening port. If a working install exists, use it and do not reinstall.

Install

From the runbook (README.ru.md, sections 2 to 4). Replace <KIT_DIR>, <SERVER_DIR> with folders you choose. <MCP_DIR> below means <SERVER_DIR>/node_modules/@sjawhar/whatsapp-mcp. In Windows PowerShell 5 run mkdir and cd as two separate lines (no &&):

git clone https://github.com/tonydzi/whatsapp-mcp-kit <KIT_DIR>
mkdir <SERVER_DIR> && cd <SERVER_DIR>
npm init -y
npm install --save-exact @sjawhar/[email protected]

Then, inside <SERVER_DIR>/node_modules/@sjawhar/whatsapp-mcp, run git apply --check <KIT_DIR>/patches/0001-qr-raw-to-stderr.patch and only then apply it (check patch 0002 separately). Make a Python venv in <KIT_DIR>/.venv and install qrcode pillow there. Do not run npm update and do not run the server with --help: some versions connect to WhatsApp at once.

Configure

  • Private env values for the pairing step: WHATSAPP_MCP_DIR (installed package folder), XDG_DATA_HOME (private per-account data folder), WA_QR_WORK_DIR (temporary QR files).
  • Pair: python <KIT_DIR>/pair/wa_qr_live.py --check, then python <KIT_DIR>/pair/wa_qr_live.py, and show the human the local page it prints.
  • <ACCOUNT_PORT> is a free local port you pick (one per account). Run one owner service per account: node <MCP_DIR>/dist/index.js --http --host 127.0.0.1 --port <ACCOUNT_PORT>, with MCP_API_KEY and ALLOWED_SEND_DIR set from a protected environment (the key is generated by you and stays out of git and argv). Never bind 0.0.0.0.
  • Connect both clients over HTTP to http://127.0.0.1:<ACCOUNT_PORT>/mcp using configs/claude-http.example.json and configs/codex-http.example.toml as examples. Codex: codex mcp add whatsapp --url http://127.0.0.1:<ACCOUNT_PORT>/mcp --bearer-token-env-var WA_MCP_TOKEN (WA_MCP_TOKEN must hold the same string as MCP_API_KEY in the environment that starts Codex).

Verify

Offline checks (no phone, no network, safe to run):

python pair/wa_qr_live.py --selftest
python pair/test_wa_qr_live.py

Expected: SELFTEST PASS and ALL GREEN (52 checks), both exit 0 (run here: matched). These prove only the QR helper's logic; they pass with no WhatsApp linked, so they are not the install check. The live proof below is. Live proof: the human sends a fresh unique word to a chat they chose, and both clients read exactly that word back, again after a controlled restart of your own owner service. A port, cached profile, old chat list or exit 0 is not proof. Report static, configured, paired, live read, live send and recipient acknowledgement separately.

Uninstall / rollback

Stop and remove only the service you created. Remove the two MCP entries you added (back up the client configs before editing). To unlink: on the phone, WhatsApp > Linked devices > remove the device. Delete the private data folder only with the human's explicit say-so; never delete auth_info to bypass a check.

Rules for the agent

  • Never print or store the QR, pairing code, bearer key, auth_info, SQLite files or chat contents in logs, reports or git.
  • Never copy auth state to another machine, never start a second WhatsApp connection on the same data folder, never kill other node processes.
  • Sending a message to anyone needs the human's approval for that exact address and text. After a send timeout the status is unknown: search for the message before retrying.
  • Do not invent flags (there is no phone-code CLI in this kit); use only what the runbook and --help of local scripts show.

Details

Connect Claude (Claude Code / Claude Desktop / Codex — any MCP client) to a WhatsApp account so it can read your chats and send messages. Includes portable setup skills, prompts, private pairing, shared HTTP configuration and recovery instructions.

(The 3-step start moved to the top of this page.) Built and battle-tested at Palo Alto AI Research Lab — our Claude fleet has been reading WhatsApp through exactly this setup since June 2026.

Current setup for Claude Code and Codex

Read the complete runbook (Russian), then use the Claude Code prompt or Codex prompt. Install the portable whatsapp-connect skill for future sessions. Both clients connect to one loopback HTTP service; they must not each launch a full WhatsApp connection.

This is one linked-device stack: @sjawhar/whatsapp-mcp + Baileys. Multiple accounts need separate private data roots and owners. The unofficial-client account restriction risk and access to private message content must be understood before linking; see security.

Pinned setup and pairing

The runbook uses isolated npm installation of version 2.4.0, checked historical patches, private environment storage and one operational supervisor. Its HTTP branch has no built-in account lock in that release; do not start another owner manually or through a second service. The docs distinguish this operational rule from enforced exclusion.

The QR helper holds stdin open and renders a refreshing local PNG page. It now rejects nonempty draft credentials: saved account/Signal-identity structure is required. That is persisted-state evidence, not fresh network connectivity. Prove a new incoming nonce in each AI client after startup and restart. A port, cached profile, old chat list or exit 0 does not prove live delivery.

For code-based phone pairing see the bounded prompt. Baileys has the API; this kit does not yet ship a ready phone-code CLI. Do not invent flags for the MCP server or launch a second socket on the same auth directory.

What is tested

Offline synthetic regression covers draft/invalid persisted state, QR parsing and helper process behavior. New phone pairing, a fresh three-OS installation and recipient acceptance have not been rerun for this documentation update. Preserve these limits in your own report.

Do not run remote prompts blindly or enter secrets in an agent conversation. Follow pairing documentation with the selected package bytes. Phone errors can have several causes; expiry is one possible cause, not a diagnosis from the wording alone. History depth is not guaranteed: measure actual sync rather than assuming a complete archive.

License

MIT (same as upstream). Upstream code is not vendored — we ship patches against it and credit the original authors: sjawhar/whatsapp-mcp-2.0, forked from karlfoster/whatsapp-mcp-2.0, built on Baileys.


Part of the connector kit series by Palo Alto AI Research Lab — see also telegram-mcp-kit and mcp-daemon-diet (one shared MCP daemon per machine instead of a copy in every session; the recipe applies to this server too). Questions / broken step? Open an issue — we answer within 24h.

AI contributors

This project is built by a human + AI team, and the git log says so: Claude writes most of the code, Codex and Grok review it, Gemini feeds the research. Each is credited on a commit only if its output changed that commit's content — no decorative credits. Lab-wide policy, one source for every repo: AI-CONTRIBUTORS.md.


Publishing your own internals? This repo was sanitized for release with oss-publish — our substitution pipeline: personal data is replaced by plausible fakes of the same shape (never <REDACTED>), and a fail-closed gate re-scans the whole tree before the push. Free, MIT.

🧰 Connector & Ops Kits

Eight kits, all published 2026-08-10, each lifted out of the same live fleet after it survived production rather than written as a demo. They are independent: take one, ignore the rest. All stdlib-only Python, all free.

kit what it solves
telegram-mcp-kit Connect your agent to your own Telegram account in ~15 minutes, with the production patches and every gotcha
whatsapp-mcp-kit Link WhatsApp, using a live self-refreshing QR page that makes pairing actually work
mcp-daemon-diet One shared MCP daemon per machine instead of a stdio copy in every session, with a watchdog that will not blind your live sessions
agent-approval-gate Your agent needs a human's OK and nobody is at the terminal: the ask goes to a messenger, the answer comes back into the run
fleet-deploy Roll a fix to N machines and prove it landed on each one: canary waves and a verify that must read a fact back
secondop-panel Nobody reviews themselves, and one reviewer model is one blind spot: fan a change out to several model families with quorum and honest skips
oss-publish Open up internal work without leaking it: plausible substitutions of the same shape, then a fail-closed gate over the whole tree
llm-spend-audit What your own wiring charges on every session, and which paid subscriptions are going undrawn

Contributors welcome — and here is what we are missing

We spend a lot of time answering other people's issues. It was fair to say out loud what we have not built ourselves:

Issues labelled accepted are scoped, free to take, and nobody is on them. Comment "claiming this" — no permission needed — and it is yours for 7 days. New here? Start with good first issue.

You keep the copyright to your code. No CLA, no assignment, ever — your contribution goes in under this repo's existing license, the same terms as ours. We answer every issue and PR within 48 hours, including "no, and here is why"; our silence is our bug, so ping the thread.

Full deal: CONTRIBUTING.md


🧩 One piece of a working system

This repository is one piece lifted out of a live operation: one engineer running a fleet of machines, built with Claude as implementation collaborator; the machines reach consensus with each other and wake the human only for money or the irreversible. It was extracted after it survived production, not written as a demo — and it runs on its own: nothing here phones home to the rest.

See how the whole thing fits together → SYSTEM.md

Its closest neighbours in the connectors layer: mcp-daemon-diet · telegram-mcp-kit

READ THIS WITH AI

One click and an agent reads the repo, pulls out the patterns and helps you apply them to your own work.

Codex - open ChatGPT - open Claude - open

Copy the prompt (works in any agent: Gemini, Grok, a local model, your own CLI)
Read this repo: https://github.com/tonydzi/whatsapp-mcp-kit (“whatsapp-mcp-kit” - Link WhatsApp to Claude (or any MCP client) in ~20 minutes: a live self-refreshing QR page that makes pairing actually work, production patches, and 12 field gotchas. On top of @sjawhar/whatsapp-mcp). Work out what problem it actually solves, pull out the reusable patterns and help me apply them to my own setup. Start by asking what I am working on.

— TonyDzi, Palo Alto AI Research Lab · second brain, agent coordination, persistent memory: github.com/tonydzi

About

Link WhatsApp to Claude (or any MCP client) in ~20 minutes: a live self-refreshing QR page that makes pairing actually work, production patches, and 12 field gotchas. On top of @sjawhar/whatsapp-mcp.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages