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.
- Open Claude Code or Codex in an empty folder on the machine that should read WhatsApp.
- 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. - 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."
- The ready-made prompt for you is
PROMPT.md(English); Russian:PROMPT-CLAUDE.ru.md,PROMPT-CODEX.ru.md. The full runbook isREADME.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.
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.
- 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, thenpython <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>, withMCP_API_KEYandALLOWED_SEND_DIRset from a protected environment (the key is generated by you and stays out of git and argv). Never bind0.0.0.0.- Connect both clients over HTTP to
http://127.0.0.1:<ACCOUNT_PORT>/mcpusingconfigs/claude-http.example.jsonandconfigs/codex-http.example.tomlas examples. Codex:codex mcp add whatsapp --url http://127.0.0.1:<ACCOUNT_PORT>/mcp --bearer-token-env-var WA_MCP_TOKEN(WA_MCP_TOKENmust hold the same string asMCP_API_KEYin the environment that starts Codex).
Offline checks (no phone, no network, safe to run):
python pair/wa_qr_live.py --selftest
python pair/test_wa_qr_live.pyExpected: 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.
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.
- 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
nodeprocesses. - 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
--helpof local scripts show.
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.
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.
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.
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.
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.
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.
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 |
We spend a lot of time answering other people's issues. It was fair to say out loud what we have not built ourselves:
- Add a phone-backup path for the full archive
- Make the patches survive
npm update - Extend
--heal-patchbeyond patch 0001
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
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
One click and an agent reads the repo, pulls out the patterns and helps you apply them to your own work.
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