# Running a WhatsApp MCP Server on Cloudflare Workers Enable AI agents to read and search personal WhatsApp messages via secure Cloudflare deployment. - **Source:** [Hacker News: Front Page](https://brifing.si/source/b07aa772-b1a0-4a76-aa18-719c6f9e2dde) - **Published:** 2026-10-18 - **Topic:** [Data & AI](https://brifing.si/c/data-ai) - **Original article:** - **On Brifing:** https://brifing.si/s/27a272d1-37e0-4cac-869d-a236d9fea176 ## WhatsApp 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. ## Technical 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. ## Deployment 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. ## Linking 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. ## Handling 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. ## Supported 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. ## Privacy 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. ## Media 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. ## Session 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. ## Extensibility 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. ## Strategic 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. ## Sources covering this story - https://github.com/finereli/whatsapp-mcp — --- _Summary written by Brifing from the original reporting. Copyright in the original article belongs to its publisher; read the full piece at the link above._