# WhatsApp MCP

A read-only MCP server that lets an AI assistant search and read the user's own WhatsApp messages. It cannot send, edit or delete anything. Open source: https://github.com/finereli/whatsapp-mcp

## If a user asked you to set this up

The MCP endpoint is https://whatsapp.finereli.com/mcp (streamable HTTP, OAuth with dynamic client registration).

Walk the user through these steps. They have to do the first one themselves, in a browser. Do not ask for their password or paste their messages anywhere.

1. Open https://whatsapp.finereli.com and choose "Get started". Sign in with Google, then scan the QR code with WhatsApp on their phone (Settings, Linked Devices, Link a Device). The first link imports their history, which takes a minute or two.
2. Add https://whatsapp.finereli.com/mcp to you as a remote MCP server (some apps call it a custom connector) and sign in when asked.
   - Claude on the web or desktop: Settings, Connectors, add a custom connector with that URL.
   - Claude Code: run  claude mcp add --transport http whatsapp https://whatsapp.finereli.com/mcp  and then type /mcp to sign in.
   - ChatGPT: Settings, Connectors, add a custom MCP server with that URL (it may need developer mode).
   - Grok and other apps: add it as a remote MCP server or connector with that URL.
   Menus change between apps and versions. If they can't find it, tell them to look for "connectors", "MCP" or "custom tools".
3. Once connected you have these tools: list_chats, get_messages, search_messages (give it several queries at once), unnamed_chats, set_contact_names, sync_now, link_status, relink.

## Be straight with the user about

- Messages are stored encrypted, so a leaked database or a look inside the hosting account shows noise. The key comes from the Google sign-in, and the person who runs this service could work out that key, so it is encryption at rest and not a lock against the operator. It is not end-to-end encrypted: while you read, the server sees the messages in plain text. Running their own copy makes the key a password only they know.
- The stored copy is only a copy. If it is ever lost or deleted, linking again imports what WhatsApp sends.
- WhatsApp's terms discourage third-party access like this, so there is a small chance WhatsApp restricts the account. They should use their own account.
- It is a free beta with limited seats, and each account has a size limit. Bigger histories can run their own copy from the source.