Running a WhatsApp MCP Server on Cloudflare Workers
Enable AI agents to read and search personal WhatsApp messages via secure Cloudflare deployment.
1WhatsApp MCP Server Overview
This project provides a server that runs within your personal Cloudflare account, allowing AI agents to read and search WhatsApp messages. By linking your phone as a secondary device, the server acts as an MCP client interface. It supports tools like message searching and chat listing without requiring official WhatsApp API access.
2Technical Architecture and Storage
The system utilizes a Cloudflare Durable Object to maintain a persistent SQLite database for message storage. All data remains within your own infrastructure, ensuring privacy. The server connects to WhatsApp only when requested by an agent or during scheduled daily pulls, minimizing active connection overhead while maintaining a reliable local message index.
3Deployment Requirements and Costs
Deployment requires a Cloudflare Workers Paid plan to accommodate necessary CPU limits for large history imports. Users must configure Node 20 or later and set up a KV namespace for OAuth tokens. The setup process involves cloning the repository, defining a strong owner password, and deploying via the Wrangler CLI tool.
4Linking and Data Synchronization
Linking your phone follows the standard WhatsApp Web QR code process. Once linked, the server performs an initial import of available message history. Subsequent synchronizations occur daily or on-demand when an agent requests data. The import process is idempotent, meaning re-linking or re-importing will not create duplicate entries in your SQLite database.
5Handling Contact Names
WhatsApp does not provide contact names for all chats to linked devices. The server identifies unnamed chats by phone number and delegates name resolution to your AI agent. By using existing contact tools, the agent can map numbers to names and save them back to the server using the set_contact_names tool.
6Supported MCP Toolset
The server exposes several tools for agents, including list_chats, get_messages, and search_messages. It also provides administrative tools like link_status and relink for session management. These tools are designed to be read-only, ensuring that the server cannot send messages or alter your WhatsApp account state, which maintains a low-risk operational profile.
7Privacy and Security Considerations
This implementation uses the open-source Baileys library to emulate a WhatsApp Web client. While this bypasses official API limitations, it technically operates against WhatsApp's terms of service. The risk is mitigated by the read-only nature of the deployment and the fact that all data resides exclusively within your private Cloudflare account.
8Media and Content Limitations
The server does not download or process media files like photos, voice notes, or documents. Instead, it displays labels such as [image] or [voice note 12s] alongside existing captions. No transcription services are integrated, keeping the server lightweight and focused strictly on text-based message retrieval and indexing for AI agent consumption.
9Session Management and Persistence
Session persistence is managed within the Durable Object, which handles Baileys authentication states. If a phone is unlinked, the server detects this during the next pull attempt. Users can trigger a re-link by scanning a new QR code, which preserves the existing message history while re-establishing the connection to the WhatsApp network.
10Extensibility for Developers
Developers can extend the functionality by registering new tools in mcp.ts or modifying the SQL schema in store.ts. The architecture is currently single-user, with the Durable Object keyed to a constant owner. Future iterations could support multi-user environments by deriving user IDs from authenticated identities and partitioning data accordingly within the database.
11Strategic Utility for AI Agents
By providing a structured interface to personal communication, this tool enables agents to perform context-aware tasks based on private chat history. It bridges the gap between siloed messaging platforms and LLM-based workflows. This integration allows for more intelligent, personalized assistance while keeping the user in full control of their sensitive data.
Original article: Hacker News: Front Page — Running a WhatsApp MCP Server on Cloudflare Workers