finereli/whatsapp-mcp

This project is an MCP server that exposes your own WhatsApp message history to MCP-capable agents such as Claude, ChatGPT or Grok. It is strictly read-only — there are no tools to send, edit or delete — and it acts as a linked WhatsApp device, the same way WhatsApp Web does. It suits people who want to query their own chats conversationally and are willing to accept WhatsApp's terms risk and, on the hosted path, a trust trade-off.

What it does and how it works

Your phone remains the source of truth. The server is a separate linked device that stays disconnected most of the time: when an agent makes a request, it connects, stores whatever WhatsApp queued, and hangs up. Messages live in a per-person SQLite database in a Cloudflare Durable Object. There is no search index, so a search decrypts and scans from newest to oldest; the author reports a full scan of 200,000 messages takes about 2 seconds, and search_messages accepts a list of queries so one pass serves several README.

Eight tools are exposed, covering chat listing, paged reading, search, unnamed-chat discovery, saving contact names, manual sync, link status and relinking README. Matching is exact-word: whole words, case and accents ignored, quoted phrases and trailing * for word starts — not fuzzy and not stemmed. Media is not downloaded; photos and voice notes appear as labels like [image] or [voice note 12s], with no transcription.

Two ways to use it

The hosted beta at whatsapp.finereli.com is the quick path: sign in with Google, scan a QR code, add the MCP endpoint to an agent. It is free during beta, has a limited number of seats and a per-account size limit project site. A setup prompt in the README lets an agent walk you through it setup assistant page.

Self-hosting requires a Cloudflare Workers Paid plan ($5/month), Node 20 or later and a phone. The paid plan matters because the first import of a large history exceeds the default CPU limit; the author has not tried the free plan and expects a fragile first import without the raised limit README. Deploying uses wrangler and sets a password (OWNER_PASSWORD, 12+ characters) from which the data key is derived.

Privacy and trust boundaries

The messages are encrypted at rest with AES-256-GCM, phone numbers and chat ids are replaced by keyed hashes, and timestamps, message types, sender side and approximate message lengths stay readable. This is not end-to-end encryption: while a request runs, the server holds the key and works with plaintext, and whoever runs the server could deploy code that captures passwords or keys. On the hosted path, the login service can derive each user's key, so encryption protects against leaked databases and backups, not against the operator; self-hosting removes that. Whatever the agent reads goes to the company running the agent. The author also notes that the people in your chats did not agree to this README. HN commenters raised the same two concerns — third-party AI ingestion of other people's messages, and WhatsApp account risk HN discussion, comment, comment. One commenter described a temporary WhatsApp restriction from linking devices through official apps, which is consistent with the author's warning that WhatsApp discourages this protocol comment.

Operational limits

There is no scheduled pull because the key only exists while someone is signed in; each read tops up if the stored copy is older than ten minutes. WhatsApp queues messages for a linked device only for a limited time, so an account unused for weeks may need a relink and reimport. History arrives once per link and may not be everything. Losing the self-hosted password means losing the stored encrypted copy (WhatsApp still has the messages). Signup, message and storage caps are optional; a too-large first import is turned away and the phone unlinked. If signing in with Google, chat names missing from WhatsApp can be filled in by the agent via a contacts tool, since the server never connects to a contacts service. The author states it has only been exercised against one real account, and edits/deletes handling has not been tested against real ones.

HotRepo's take

The repository was created 2026-10-18 and appeared on HotRepo's NEW-REPOSITORY board at 387 total stars on 2026-10-26; there is no comparable daily-board history, so the supplied evidence says nothing about momentum. Treat the documented trade-offs above, not the star count, as the basis for a decision.