finereli/whatsapp-mcp

What it is

whatsapp‑mcp is a small self‑hosted server that lets an AI agent (e.g., Claude Code) read and search the contents of your WhatsApp chats. It runs as a Cloudflare Workers service, stores the messages in a SQLite database inside a Durable Object, and exposes a simple MCP (Message‑Control‑Protocol) endpoint that agents can call.

How it works

1. Linking – You scan a QR code (or use the phone‑number method) from the web UI, just like adding a device to WhatsApp Web. The server becomes a linked device and pulls the chat history that WhatsApp makes available for a new device.
2. Storage – All messages, chat metadata and a full‑text‑search index are kept in a SQLite DB inside the Durable Object. No data is sent elsewhere.
3. Pulling – Once a day (or on demand) the server reconnects to WhatsApp, fetches any new messages that arrived since the last pull, updates the DB, and disconnects. The phone continues to work normally.
4. Agent access – An AI agent talks to the /mcp endpoint using the MCP tool set (list chats, get messages, search, etc.). The server first makes sure the DB is fresh (pulls if older than 10 min) and then returns the requested data.

Main features (MCP tools)

Tool	What it does
list_chats	Returns chats ordered by recent activity, with optional name/number filter.
get_messages	Retrieves messages from a single chat, with pagination by date.
search_messages	Full‑text search across all chats or within a specific chat.
unnamed_chats	Lists chats that only have a phone number (no saved contact name).
set_contact_names	Saves a custom name for a phone number; the name is used in future queries.
sync_now	Forces an immediate pull of new WhatsApp messages.
link_status	Shows whether the device is linked, last pull time, and storage size.
relink	Unlinks the device so you can scan a new QR code; existing stored messages are kept.

Setup steps (high‑level)

1. Prerequisites – Cloudflare account on the Workers Paid plan, Node 20+, and a phone with WhatsApp.
2. Clone & install – git clone … && npm install.
3. Create KV namespace – npx wrangler kv namespace create OAUTH_KV and paste the printed ID into wrangler.jsonc.
4. Set a password – npx wrangler secret put OWNER_PASSWORD (12+ characters).
5. Deploy – npm run deploy. Wrangler prints a URL like https://whatsapp-mcp.your-name.workers.dev.
6. Link WhatsApp – Open the URL, scan the QR code (or use the phone‑number option). The first import may take a while.
7. Connect an agent – In Claude Code run claude mcp add --transport http whatsapp https://your-url/mcp and then use the /mcp command with the password you set.

Important limitations & risks

• Unofficial – It uses the same reverse‑engineered protocol as WhatsApp Web (via the Baileys library). This violates WhatsApp’s terms of service; the practical risk is low for a read‑only device but not zero.
• Read‑only – No ability to send messages; the server deliberately does not expose a send API.
• One‑user only – Each deployment is tied to a single WhatsApp account and owner password. Multi‑user support would require code changes.
• No media download – Images, voice notes, etc. appear as placeholders like [image]; they are not fetched or transcribed.
• Contact names – Chats without a saved contact appear as phone numbers. The agent must call unnamed_chats and then set_contact_names to give them a readable name.
• Paid Cloudflare plan – Importing a large history needs higher CPU limits, which are only available on the paid Workers plan.
• Potential breakage – Because the server relies on a reverse‑engineered protocol, future WhatsApp updates could stop it from working.

Who might use it

• Developers building AI assistants that need personal context (e.g., “What did my friend say about the flight?”).
• Privacy‑conscious users who want the data to stay in their own Cloudflare account rather than a third‑party service.
• Researchers experimenting with LLM‑driven personal agents.

License

MIT – you can freely use, modify, and deploy the code.