WhatsApp MCP server gives AI agents read-only access to your chats on Cloudflare

What the server does

A developer publishing as finereli has released whatsapp-mcp, an open-source MCP server that gives AI agents read-only access to your WhatsApp history. According to the project's README, shared on Hacker News as a Show HN post, the server deploys into your own Cloudflare account, and you link your phone once by scanning a QR code — the same flow used to pair WhatsApp Web. After that, any MCP client such as Claude Code or Claude Desktop can ask what a specific person said about travel plans, search every chat for a keyword, or summarize a busy group conversation from the past week.

The server deliberately cannot send anything. Its toolset covers listing chats, paging through individual conversations by date, full-text search across the archive, and saving human-readable names against phone numbers so those names also appear correctly inside group chats.

How it works

The phone remains the authoritative copy; the server registers itself as another linked device. It does not hold a permanent connection. When an agent requests something — or on a daily schedule — it connects, collects whatever WhatsApp has queued, writes it into its own database, and disconnects, leaving the phone's notifications untouched. Every read operation also refreshes the stored copy if it is more than ten minutes old.

The data lives in a SQLite database inside a Durable Object in the user's Cloudflare account, backed by an FTS5 full-text index. The front-end Worker is otherwise stateless, with a KV namespace holding OAuth tokens. Getting Baileys, the open-source library that implements WhatsApp's web protocol, to run on Cloudflare's workerd runtime required a set of shims and polyfills, the README notes.

One design choice stands out: WhatsApp hands a linked device only the contact names it already knows, so many chats arrive as bare phone numbers. Rather than having the server log into a contacts service — which would mean OAuth consent screens and, for Google, app review — it delegates the job to the agent, which usually already has a contacts connector, and stores whatever names it resolves.

The fine print

Despite the Show HN title promising a free run, the README concedes the setup needs Cloudflare's Workers Paid plan, a few dollars per month. Importing a large history exceeds the default CPU limit on Workers, so the configuration raises it, and raising limits requires the paid tier. The author has not tested the free plan; without the raised limits the first import is expected to be fragile.

The larger caveat is legitimacy. WhatsApp offers no official API for reading personal messages, and the project works by speaking the same protocol as WhatsApp Web, which the README acknowledges violates the platform's terms of service. The author's assessment is that the practical risk for a read-only linked device is low but not zero. Media files are never downloaded — photos and voice notes surface only as placeholder labels — and each deployment serves exactly one account and one owner by design, since it holds a full message history plus live credentials.

A companion guide to remote MCP

A guide published on dev.to around the same time uses the project as a jumping-off point for deploying remote MCP servers on Cloudflare Workers in general. Its author, who moved internal tools such as order lookups, log readers and note storage from local stdio servers to Workers, lists three pain points remote servers solve: installing and configuring a server on every machine, API secrets scattered across per-user config files, and cloud-hosted agents that cannot spawn processes on your laptop.

According to the guide, the approach rests on the Streamable HTTP transport added to the MCP spec in March 2025, Cloudflare's free tier of 100,000 requests per day, and Durable Object-backed session state. Among the gotchas it documents: free-plan migrations must declare Durable Object classes with new_sqlite_classes rather than the older option, or deploys fail; the Accept header must include text/event-stream or the server rejects requests with a 406; tool descriptions function as prompts, so they should be written deliberately; and inputs should be validated with Zod while result sizes are capped, so oversized model output does not burn context and tokens. A six-person team running a few thousand requests per day stayed comfortably inside the free tier, the author reports.

Why it matters

This is really two stories. One is a working pattern for giving agents access to personal messaging data that platforms deliberately keep behind official APIs — effective, but built on terms-of-service-violating ground that could break at any time. The other is evidence that remote MCP deployment has become cheap and simple enough to be a default rather than an exception: near-zero cold starts, SQLite-backed Durable Objects on the free tier, and a single URL plus a token replacing per-machine setup. The WhatsApp project's architecture — a stateless Worker in front of one Durable Object — is precisely the shape the dev.to guide teaches generically, which suggests the next wave of agent tools will look a lot like both.