Read Your WhatsApp with an AI Agent on Cloudflare Workers — whatsapp-mcp Walkthrough
By Arash Latifi
whatsapp-mcp lets your AI agent search and read your WhatsApp messages — no server, running in your own Cloudflare account. Setup, limits, and risks.
TL;DR — whatsapp-mcp is a read-only MCP server that runs in your own Cloudflare account and stores your WhatsApp messages in a Durable Object, so Claude Code or any MCP client can search and summarize them — mind the Workers Paid plan requirement and the ban risk.
The problem it solves
Your AI agent travels everywhere with you, but it can't see your WhatsApp messages. Existing options either require WhatsApp Business API (not for personal accounts) or a dedicated server to run Baileys. This project — which hit 157 points on Hacker News on Oct 22, 2026 — sidesteps both: everything runs in your own Cloudflare account and links your personal account the same way WhatsApp Web does.
Questions you can ask after setup:
- "What did Dana say about the flights?"
- "Find every message where someone mentioned the lease, across all my chats."
- "Summarize what I missed in the family group this week."
How it works
The neat part of the architecture: your phone stays the source of truth, and the server is just a linked device.
- It doesn't stay connected to WhatsApp. When your agent asks something (and once a day), it connects, collects whatever WhatsApp queued since last time, writes it to a SQLite database inside a Durable Object, and hangs up.
- Messages live in that SQLite database in your own Cloudflare account — "nothing goes anywhere else," per the README.
- Sending is not supported; read and search only.
The HN discussion raised a fair concern: this exposes the other side of your conversations — the people messaging you never consented to their words being fed to an AI model. Worth weighing before you use any tool like this. Another commenter shared real-world experience with Baileys-style libraries: accounts occasionally get banned, which stings if WhatsApp is your primary contact channel.
Step-by-step setup
Prerequisites: a Cloudflare account on the Workers Paid plan, Node 20+, and your phone.
Wrangler prints a URL like https://whatsapp-mcp.your-name.workers.dev. Its front page has the two remaining steps:
- Link WhatsApp: scan the QR code with WhatsApp (Settings ← Linked Devices ← Link a Device). The first link imports your history.
- Connect your agent: in Claude Code:
Then type /mcp and sign in with the password. Other MCP clients point at the same /mcp URL.
Tools your agent gets
| Tool | What it does |
|---|---|
| list_chats | Chats, most recent first, filter by name or number |
| get_messages | Read one chat, page back/forward by date |
| search_messages | Full-text search across everything, or within one chat |
| unnamed_chats | Chats known only by phone number, busiest first, with the last message |
| set_contact_names | Save names for numbers — they stick to the number and show in groups too |
| sync_now / link_status / relink | Force a sync, check link state, relink with a new QR |
Every read tool tops up from WhatsApp first if the stored copy is more than ten minutes old.
Limits you should know
- Why the paid plan? Importing a large history decodes a lot of data in one go, and the default Workers CPU limit is too small.
wrangler.jsoncraises it, and raising it needs the paid plan (a few dollars a month). On the free plan you'd remove thelimitsblock and expect a fragile first import. - Unofficial and against WhatsApp's terms. WhatsApp has no API for reading your own personal messages; this uses the WhatsApp Web protocol via the open-source Baileys library. For a read-only linked device the practical risk is low but not zero. Use it on your own account, never to send.
- History isn't guaranteed complete. WhatsApp hands a new device whatever it decides, once per link. Re-importing requires relinking (stored messages are kept).
- Media isn't downloaded. Photos, voice notes and files appear as labels like
[image]or[voice note 12s]with captions. - Single-user by design. One deployment holds a full message history and a live login, so it's deliberately one account, one owner.
One clever design decision: WhatsApp doesn't give a linked device every contact name, so instead of logging into a contacts service, the server delegates to your agent. You say "find names for my unnamed chats"; the agent calls unnamed_chats, matches numbers via your contacts connector (e.g. Google Contacts), and saves them with set_contact_names. Even "no chat found" results nudge the agent toward doing this.
Setup checklist
- [ ] Cloudflare account on Workers Paid, Node 20+ ready
- [ ] KV namespace created and its id pasted into
wrangler.jsonc - [ ]
OWNER_PASSWORDset with 12+ characters - [ ] QR scanned and history import completed
- [ ]
claude mcp add --transport http whatsapp https://your-url/mcprun and/mcpsigned in - [ ] Important unnamed chats named via
set_contact_names - [ ] You accept the (small) ban risk and won't use a work-critical account