A developer has released an open-source project that connects WhatsApp to AI agents through the Model Context Protocol (MCP), letting tools like Claude Desktop or Claude Code search and read a person’s own WhatsApp messages. Shared on Hacker News under the “Show HN” tradition for independent projects, the tool runs entirely inside the user’s own Cloudflare account rather than on a third-party server, which is the detail generating the most interest. It matters because it points to a growing pattern: developers building personal, self-hosted bridges between everyday messaging apps and AI agents, using infrastructure they fully control.

What the WhatsApp MCP server actually does

The project is a read-only MCP server. MCP, short for Model Context Protocol, is the emerging standard that lets AI applications like Claude connect to external tools and data sources in a consistent way. Once this server is deployed, any MCP-compatible client can query it to search and read a user’s WhatsApp chat history and remember custom names for phone numbers. It cannot send messages, which the developer frames as a deliberate safety boundary rather than a limitation to be fixed later.

Setup mirrors the familiar WhatsApp Web flow: the user scans a QR code from their phone’s Linked Devices menu, which registers the Cloudflare-hosted server as a linked device. From that point, the phone remains the “source of truth” for messages, and the server periodically checks in to sync new data.

How it works without staying permanently connected

Unlike a service that maintains a constant live connection to WhatsApp, this server deliberately stays mostly offline. It connects to WhatsApp only when an AI agent makes a request, or at most once a day, pulls down whatever messages WhatsApp has queued since the last check, writes them into its own database, and disconnects again. The phone continues to receive notifications normally and is unaffected by this syncing in the background.

Technically, messages are stored in a SQLite database running inside a Cloudflare Durable Object, a Cloudflare Workers feature designed for stateful, per-object storage. According to the project, nothing is sent to any external server beyond the user’s own Cloudflare account, which is the core privacy pitch: the data footprint is limited to infrastructure the user already pays for and controls.

Built on an unofficial protocol, with real tradeoffs

WhatsApp does not provide an official API for reading a personal account’s own messages. To work around this, the project uses Baileys, an open-source library that replicates the same protocol WhatsApp Web itself uses. The developer is upfront that this approach violates WhatsApp’s terms of service. Because the linked device only reads data and never sends messages, the stated risk of account action is described as low, but not zero — a caveat worth taking seriously given WhatsApp’s history of restricting unofficial clients.

There are also functional limits baked into the design. The initial link imports whatever message history WhatsApp chooses to hand to a new linked device, which may not be a complete archive; relinking the device can backfill missing messages later. Media such as photos, voice notes, and documents are not downloaded or transcribed — they appear only as placeholder labels like [image] or [voice note 12s], along with any caption. And because WhatsApp doesn’t share full contact names with linked devices, many chats initially show up only as raw phone numbers.

Letting the AI agent fill in contact names

That last limitation is handled in an interesting way. Rather than have the server itself connect to a contacts service, which would require setting up a cloud project and consent screens, the developer pushes that job onto the AI agent. The agent can list unnamed chats, cross-reference the phone numbers using whatever contacts tool it already has access to (for example, a connected Google Contacts or Gmail integration), and then save the resulting names back into the MCP server. The server’s own connectivity is limited strictly to WhatsApp, keeping its scope narrow and its permissions easier to reason about.

What this means for developers who want to try it

The project is explicitly designed for single-user deployment: one Cloudflare deployment corresponds to one WhatsApp account and one owner, since each instance holds a full message history and an active login. Anyone wanting to use it needs their own Cloudflare account, specifically on the paid Workers plan, Node 20 or later, and their phone to scan the initial QR code.

The paid plan requirement comes down to a practical constraint: importing a large message history decodes a significant amount of data at once, exceeding the CPU limits available on Cloudflare’s free Workers tier. The project’s configuration file raises that CPU limit, which requires the paid plan to function reliably; the developer notes they haven’t tested the free tier and expect it to struggle with a first-time import.

For developers already experimenting with MCP and agent tooling, this project is a concrete example of how self-hosted, narrowly scoped integrations can be built on top of unofficial protocols without handing message data to a third party. For everyone else, it’s worth weighing the convenience of chat-searching AI agents against the acknowledged risk of relying on an unofficial WhatsApp protocol implementation, and against WhatsApp’s own terms of service.

Frequently asked questions

Can this tool send WhatsApp messages on my behalf?
No. It is explicitly read-only; it can search, read, and label chats, but it has no capability to send messages.

Is this an official WhatsApp feature?
No. It relies on Baileys, an open-source library replicating the WhatsApp Web protocol, which is against WhatsApp’s terms of service, though the developer notes the practical risk is described as low for a read-only linked device.

Where is my message data actually stored?
Inside a SQLite database running in a Durable Object within the user’s own Cloudflare account, rather than on any server operated by the project’s developer.

Source: Show HN: WhatsApp MCP running free on Cloudflare