Tram cong nghe AI
WhatsApp MCP is a new open-source server that lets an AI agent such as Claude search and read your personal WhatsApp messages, running inside your own Cloudflare account. It was shared on Hacker News on October 18, 2026 as “running free on Cloudflare,” where it reached 94 points and 48 comments. The catch: the setup guide asks for a paid Cloudflare plan, and the author openly says the method is against WhatsApp’s terms.
Key Takeaways
- What it is: WhatsApp MCP is a small, read-only server that connects your personal WhatsApp account to any MCP client, including Claude Code and Claude Desktop.
- Read-only: your agent can read and search chats and save names for phone numbers. It cannot send anything.
- Where your data lives: in a SQLite database inside a Durable Object in your own Cloudflare account. “Nothing goes anywhere else,” according to the author.
- Real cost: the guide requires the Cloudflare Workers Paid plan, which the author describes as “a few dollars a month.” The free plan is untested.
- The risk: it uses the same protocol as WhatsApp Web through the open-source Baileys library. The author says this is against WhatsApp’s terms, with a low but non-zero practical risk.
- Who it is for: one person, one WhatsApp account, one deployment. License: MIT.
What Is WhatsApp MCP?
MCP stands for Model Context Protocol. It is a standard way for AI assistants to plug into outside tools and data. An “MCP server” exposes tools; an “MCP client” (like Claude Code) calls them.
WhatsApp has no official API for reading your own personal messages. The author wanted Claude on mobile to access their WhatsApp, but the options they found either required WhatsApp Business or a real server running Baileys. So they built WhatsApp MCP to run on Cloudflare Workers with a personal account.
Here is how it works:
- You link your phone once, the same way you link WhatsApp Web (Settings, Linked Devices, Link a Device).
- The server becomes a linked device. Your phone stays the source of truth and keeps getting notifications as normal.
- The server does not stay connected. When your agent asks for something, and once a day, it connects, collects what WhatsApp queued since last time, saves it to its own database, and hangs up.
- Every read tool first tops up from WhatsApp if the stored copy is more than ten minutes old.
Once connected, you can ask your agent questions like “What did Dana say about the flights?” or “Summarize what I missed in the family group this week.”
WhatsApp MCP Tools: What Your Agent Can Do
The WhatsApp MCP server gives your agent eight tools:
| Tool | What it does |
|---|---|
list_chats | Lists chats, most recent first. Filter by name or number. |
get_messages | Reads one chat, paging back or forward by date. |
search_messages | Full-text search across all chats or within one. |
unnamed_chats | Shows chats known only by phone number, busiest first. |
set_contact_names | Saves names for phone numbers. Names also show up in groups. |
sync_now | Pulls new messages right now. |
link_status | Shows whether it is linked, the last pull, and how much is stored. |
relink | Unlinks and starts over. A human must scan the new QR code. |
Fixing chats that only show phone numbers
WhatsApp does not give a linked device every contact name. Instead of logging in to a contacts service itself, WhatsApp MCP hands that job to your agent. Say “find names for my unnamed chats.” The agent calls unnamed_chats, matches numbers using a contacts tool it already has (for example a Google Contacts or Gmail connector), and saves the names with set_contact_names. It will not find everyone, because most unnamed chats are single messages from strangers.
How to Set Up WhatsApp MCP in 3 Steps
You need a Cloudflare account on the Workers Paid plan, Node 20 or later, and your phone. The author also suggests pointing your own agent at the repo and letting it handle the setup.
Step 1: Deploy to Cloudflare
git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install
# A place for sign-in tokens. Paste the id it prints into wrangler.jsonc.
npx wrangler kv namespace create OAUTH_KV
# A password for the page that links your phone (12+ characters).
npx wrangler secret put OWNER_PASSWORD
# Deploy.
npm run deployWrangler (Cloudflare’s command-line tool) prints your URL, something like https://whatsapp-mcp.your-name.workers.dev.
Step 2: Link WhatsApp
Open the URL and scan the QR code with WhatsApp. If you are on the phone itself, use the phone number option instead. The first link imports your history. The page shows progress, and you can close it without stopping the import.
Step 3: Connect your agent
In Claude Code:
claude mcp add --transport http whatsapp https://your-url/mcpThen type /mcp and sign in with your password. Other MCP clients can point at the same /mcp URL. If you already use other MCP servers, our Playwright MCP guide explains the same client-side flow in more detail.
WhatsApp MCP Cost: Is It Really Free?
The Hacker News title says “running free on Cloudflare,” but the setup guide tells a different story.
| Item | What the source says |
|---|---|
| Software | Free and open source (MIT license) |
| Cloudflare plan in the guide | Workers Paid plan, “a few dollars a month” |
| Cloudflare free plan | Not tried by the author; first import “expected to be fragile” |
| WhatsApp Business | Not required; works with a personal account |
Why the paid plan? Importing a large chat history decodes a lot of data at once, and the default CPU limit on Workers is too small. The project’s wrangler.jsonc file raises that limit, which needs the paid plan. If you want to try the free plan, the author says to remove the limits block and expect problems on the first import.
So the honest answer: WhatsApp MCP costs nothing to download, but the documented setup costs a few dollars a month.
WhatsApp MCP Risks and Limits
This is the part the video warned about. Read it before you scan any QR code.
It breaks WhatsApp’s terms. In the author’s words: “This isn’t official.” WhatsApp MCP uses the WhatsApp Web protocol through Baileys, and “that’s against WhatsApp’s terms.” For a linked device that only reads, the author calls the practical risk low, “but it isn’t zero.” Their advice: use it only on your own account, and do not use it to send messages.
It holds very private data. Each deployment stores a full message history and a live login to your account. That is why it is designed for one person only. Everyone should run their own deployment. For a wider look at how AI tools handle personal data, see our piece on AI chatbot privacy and trackers.
Your history may be incomplete. The first link imports whatever history WhatsApp decides to hand a new device. It may not be everything. To import again, you relink. Stored messages are kept, and a re-import fills in gaps without duplicates.
No media. Photos, voice notes and documents appear only as labels like [image] or [voice note 12s], plus any caption. Nothing is downloaded or transcribed.
Relinking. If your phone says the device was removed, ask your agent to run relink, or open /setup and choose “Unlink and scan again.”
Is WhatsApp MCP Worth It?
Pros
- Lets Claude and other MCP clients search and summarize your real WhatsApp conversations.
- Read-only by design, so your agent cannot send messages on your behalf.
- Your data stays in your own Cloudflare account.
- No WhatsApp Business account and no always-on server to maintain.
- Smart contact-naming that reuses tools your agent already has.
Cons
- Against WhatsApp’s terms, with a small but real account risk.
- The documented setup needs a paid Cloudflare plan, despite the “free” headline.
- Requires comfort with the command line and Cloudflare.
- No media download, and history import may be partial.
If you live in WhatsApp and already work with Claude Code, WhatsApp MCP is a clever way to make your chats searchable by AI. If your WhatsApp account is critical for work or family, the terms-of-service risk deserves serious thought first. If you are new to agents, start with our Claude Code subagents workflow to get comfortable with the tooling.
WhatsApp MCP FAQ
Is WhatsApp MCP official?
No. WhatsApp has no API for reading your own personal messages, and the author says this approach is against WhatsApp’s terms.
Can WhatsApp MCP send messages?
No. It can read and search messages and save names for phone numbers, but it cannot send anything.
Is WhatsApp MCP free?
The code is free under the MIT license, but the setup guide requires the Cloudflare Workers Paid plan, which the author says costs a few dollars a month.
Does WhatsApp MCP work with Claude?
Yes. It works with Claude Code, Claude Desktop and any client that speaks MCP.
Where are my messages stored?
In a SQLite database inside a Durable Object in your own Cloudflare account. According to the author, nothing goes anywhere else.
Sources
Last updated: October 19, 2026
