WhatsApp MCP ⚡ Search Chats with AI—Private & New

Read-only is a useful boundary, but it's not a magic shield

The server can search chats, retrieve messages, and help you assign names to phone numbers. It can't send messages. That's a real difference from an automation that can reply or take actions on your behalf.

The tools include:

• list_chats to show chats, with filtering by name or number.
• get_messages to read messages in a particular chat and page through them by date.
• search_messages to search across stored messages or within a chat.
• unnamed_chats to identify chats that only have a phone number.
• set_contact_names to save a readable name for a number.
• sync_now to request a new sync of available messages.

But permissions don't tell the whole security story. Even if the agent can't send WhatsApp messages, it can still read sensitive conversations. And if your client forwards retrieved content to a hosted AI service, that content may be processed outside the Cloudflare account where the server runs. Read-only lowers the risk of accidental outbound messages - but it doesn't make the data "non-sensitive."

Who it's for

This is aimed at a person who wants to ask questions about their own WhatsApp history and is willing to deploy a small server. It isn't positioned as a team inbox, a business messaging integration, or a way to query many users from one shared service.

That single-owner setup is intentional. Each deployment keeps its own message history and a linked-device login, so each person should run their own instance. If you're looking for customer support automation or a shared company workflow, this isn't the place to start. For those, look at a platform-supported business product with documented permissions.

Deployment requirements

The README asks for a Cloudflare account on the Workers Paid plan, Node.js 20 or later, and a phone with WhatsApp. The paid plan is meant to handle the CPU cost of importing a large message history, since it can exceed the default Workers CPU limit. The configuration raises that limit, which requires a paid account. The author estimates the cost is a few dollars a month, but pricing and limits can change - so check Cloudflare's current terms before you deploy.

Setup, in broad strokes:

1. Clone the repository and install its dependencies.
2. Create a Cloudflare KV namespace for OAuth tokens and add the namespace ID to the Wrangler configuration.
3. Set an owner password of at least 12 characters for the setup page.
4. Deploy the Worker.
5. Open the deployed URL and link WhatsApp by scanning a QR code, or use the phone-number option where available.
6. Add the /mcp endpoint to an MCP client and authenticate with the owner password.

For example, the README shows this command for Claude Code:

claude mcp add --transport http whatsapp https://your-url/mcp

Client setup will vary. Use the MCP instructions for your specific client and check what data it sends to its model provider. For background, see the Model Context Protocol documentation.

Names, history, and media

Some chats may show up as phone numbers only, since a linked device doesn't always get every contact name. WhatsApp MCP lets you save names for numbers. The project suggests using a contacts connector already available to your AI client to look up names, then saving them via the server. The server itself doesn't connect to a contacts provider.

The server also doesn't download media. Photos, voice notes, and documents are represented with labels like [image] or [voice note 12s], plus captions when available. In other words, it can't inspect a photo, listen to a voice note, or transcribe audio based on what it represents.

If you remove the linked device or want to reconnect, the README says you can use the relink tool or the /setup page to unlink and scan again. Stored messages are kept, and a new link can fill in missing history. Relinking is a recovery option, not a guarantee that WhatsApp will provide a complete archive.

Use summaries as a map, not as proof

An AI summary is a good index into what you said - just not a substitute for reading the actual messages. Group chats can include jokes, corrections, replies to earlier messages, and references that only make sense in context. Searching might pull up a relevant phrase, without showing what happened around it.

For anything involving money, travel, health, work, or an agreement, ask the agent to point you to the messages it used and verify the exchange yourself. The tools can retrieve messages, but they don't automatically make the model's interpretation correct. A practical workflow looks like this:

1. Ask a narrow question with a person, subject, or timeframe.
2. Request the relevant messages or dates along with the summary.
3. Check the original conversation before you act.

This isn't unique to WhatsApp MCP. It's a general rule for retrieval systems: better access to source material improves grounding, but it doesn't guarantee interpretation is right.

Know what it can't do

The feature set is intentionally constrained. It doesn't send messages, download media, or transcribe voice notes. It also can't retrieve information that WhatsApp never delivered to the linked device - or information the server hasn't synchronized yet.

There are also practical limits. Importing an initial history can be CPU-heavy, and the author notes the free Workers plan may make imports fragile if the CPU-limit configuration isn't in place. Re-importing requires relinking, and completeness depends on what WhatsApp provides. Chats that are phone-number-only may require manual naming work.

Those limitations aren't necessarily a problem. They make the system easier to reason about than a setup that reads media, interprets it, and sends replies automatically. But if you need a complete searchable archive, audio transcription, or something that works like business-grade message handling, you should validate those requirements before building your process on top of it.

The linked-device credential is sensitive

A linked device gives the server access to whatever messages are available to that device. Treat the Worker, the owner password, and any stored authentication data as sensitive. Use a strong unique password, restrict access to the deployment, and don't share one deployment across users. The project's one-person-per-deployment model is a sensible default because each instance holds a personal history and login.

Also consider the people in your conversations. Your contacts may not have expected an AI system to analyze their messages. That doesn't automatically mean every use is inappropriate, but it should affect what you query, what you share, and whether you use the tool in group or work-related chats. Don't paste sensitive summaries into other services until you've checked how those services handle data.

WhatsApp policy is a real trade-off

The project is explicit that this isn't an official WhatsApp integration. It uses Baileys, an open-source library that communicates using the protocol WhatsApp Web uses. The README says this approach goes against WhatsApp's terms. The project author argues the risk for a read-only linked device is low, but it's not zero.

That's still the author's assessment, not a guarantee from WhatsApp. Account enforcement policies and technical behavior can change. Only use it with your own account, understand you could face consequences, and don't try to repurpose the server to send messages or access other people's accounts. If losing access to your WhatsApp account would be a serious issue, the risk may not be worth the convenience.

A good decision test is to ask three questions first:

• Is the task worth the data exposure? If you only search infrequently, connecting an AI service may add more risk than value.
• Can you explain the full data path? Don't stop at the database - include Cloudflare, the MCP client, and the model provider.
• Can you accept the platform risk? This integration is unofficial, and it doesn't remove the uncertainty.

If you can answer those clearly, a personal read-only setup may be a reasonable experiment. If you can't, "self-hosted" shouldn't be treated as a complete privacy solution.