Running a WhatsApp MCP Server on Cloudflare Workers
Enable AI agents to read and search personal WhatsApp messages via Cloudflare infrastructure.
1WhatsApp MCP Architecture
This project implements a Model Context Protocol server that allows AI agents to read personal WhatsApp messages. It operates as a linked device, similar to WhatsApp Web, utilizing the open-source Baileys library to interface with the protocol. The server runs entirely within a user-owned Cloudflare account, ensuring data remains private and self-contained.
2Infrastructure and Deployment
The server requires a Cloudflare Workers Paid plan to accommodate the CPU limits necessary for processing large message histories. Deployment involves cloning the repository, configuring a KV namespace for tokens, and setting a password. The system uses Durable Objects to maintain a persistent SQLite database, which stores all ingested messages and authentication keys.
3Data Synchronization Mechanism
The server does not maintain a constant connection to WhatsApp. Instead, it triggers a synchronization process once daily or upon an agent's request. During these sessions, it collects queued messages, updates the local SQLite database, and terminates the connection. This design ensures the phone remains the primary source of truth for all communications.
4Handling Contact Names
WhatsApp does not provide contact names for every chat to linked devices. Consequently, many chats appear as phone numbers. The system delegates name resolution to the AI agent, which can cross-reference numbers with external contact lists. Users can then save these names using the set_contact_names tool, which persists the data locally.
5Privacy and Security
All message data resides exclusively within the user's Cloudflare Durable Object. The server does not connect to external contact services directly, preventing unauthorized data exposure. Because the implementation relies on the WhatsApp Web protocol, it is not an official API, and users should avoid using it for sending messages to minimize risk.
6Core MCP Toolset
The server exposes several tools for agents, including list_chats, get_messages, and search_messages. These tools allow for full-text searching across the entire message history or within specific conversations. The sync_now tool forces an immediate update, while link_status provides visibility into the current connection state and the number of unnamed chats currently stored.
7Idempotent Data Ingestion
The ingestion process is designed to be idempotent, meaning re-importing history will not create duplicate entries. If a re-link occurs, the system fills in missing data such as sender names or push_names without altering existing records. This mechanism ensures that the local database remains consistent even if the connection is reset or refreshed.
8Technical Limitations
Media files like photos, voice notes, and documents are not downloaded or transcribed. Instead, the system displays labels such as [image] or [voice note] along with any existing captions. This limitation is a deliberate design choice to maintain simplicity and reduce the storage overhead within the Cloudflare Durable Object environment.
9Multi-User Considerations
The current implementation is strictly single-user, with one deployment tied to one WhatsApp account. The Durable Object is addressed by a fixed name, and the user identity is constant. Expanding to multi-user support would require deriving the object key from the signed-in identity, which involves significant architectural changes regarding data isolation.
10Development and Debugging
Developers can test the system locally using a .dev.vars file and the wrangler CLI. The project includes specific debug routes protected by a PIN header, allowing for the inspection of session states and pairing status. Automated tests run against Node's built-in SQLite, ensuring that migrations and core storage logic remain functional.
11Strategic Implications
By bridging personal messaging platforms with AI agents via MCP, this project demonstrates a path for context-aware automation. It highlights the trade-offs between using unofficial protocols and the utility of local, private data storage. For professionals, this provides a template for integrating siloed communication data into broader AI-driven productivity workflows.
Original article: Hacker News: Show HN — Running a WhatsApp MCP Server on Cloudflare Workers