finereli / whatsapp-mcp

# whatsapp-mcp
Let your AI agent read your WhatsApp messages.
This is a small server that runs in your own Cloudflare account. You link your phone to it once, the way you'd link WhatsApp Web, and from then on any MCP client (Claude Code, Claude Desktop, anything that speaks MCP) can search and read your chats. It can read and search your messages, and remember names you give it for phone numbers. It can't send anything.
Ask your agent things like:
- "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
Your phone stays the source of truth. The server is a linked device that your agent talks to.
It doesn't stay connected to WhatsApp. When your agent asks for something, and once a day, it connects, collects whatever WhatsApp queued for it since last time, writes that to its own database, and hangs up. Your phone keeps working normally and keeps getting notifications.
Your messages live in a SQLite database inside a Durable Object in your Cloudflare account. Nothing goes anywhere else.
## Set it up
You need a Cloudflare account on the Workers Paid plan (see the note below), Node 20 or later, and your phone.
 [code] 
Wrangler prints your URL, something like `https://whatsapp-mcp.your-name.workers.dev`. Open it. The front page has the two remaining steps:
1. **Link WhatsApp.** Scan the QR code with WhatsApp (Settings, Linked Devices, Link a Device). If you're on the phone itself and can't scan a screen, use the phone number option instead. The first link imports your history. The page shows progress, and you can close it.
2. **Connect your agent.** In Claude Code:
 [code] 
 Then type `/mcp` and sign in with the password. Other clients: point them at the same `/mcp` URL.
If you want your own domain, see the comments at the bottom of `wrangler.jsonc`.
### The Workers Paid note
Importing a large history decodes a lot of data in one go, and the default CPU limit on Workers is too small for it. `wrangler.jsonc` raises it, and raising it needs the paid plan, which is a few dollars a month. I haven't tried the free plan. If you're on it, remove the `limits` block and expect the first import to be fragile.
## Things to know
**This isn't official.** WhatsApp has no API for reading your own personal messages. This uses the same protocol WhatsApp Web uses, through an open source library (Baileys). That's against WhatsApp's terms. For a linked device that only reads, the practical risk is low, but it isn't zero. Use it on your own account, and don't use it to send messages.
**You get what WhatsApp sends.** The first link imports whatever history WhatsApp decides to hand a new device. It may not be everything. It only does this once per link. To import again, relink (your stored messages are kept, and a re-import fills in anything missing).
**Some chats show up as phone numbers.** WhatsApp doesn't give a linked device every con