WhatsApp MCP

Let Claude read your own WhatsApp: summaries, search, pictures, voice notes and videos. It never sends a message. Your messages stay on your computer, encrypted.

中文说明

Easiest setup: let your AI do it

If you use Claude Code, open it and say:

Set up this app for me: https://github.com/stevenpkm/whatsapp-mcp-desktop

The agent follows AGENTS.md and does every step itself. You only restart Claude Code once and scan a QR code with your phone. Claude Code needs Node 22.5 or newer; the agent checks it.

Related MCP server: WhatsApp MCP

Setup in Claude Desktop, step by step

Works on Windows and Mac. No Node, no terminal, no ports to open.

Step 1. Install Claude Desktop Download it from claude.ai/download, install it and sign in.

Step 2. Download the install file Go to Releases and download whatsapp-mcp-desktop.mcpb.

Step 3. Install it in Claude Double-click the file. Claude opens and shows the extension. Press Install. Nothing happens? Open Claude > Settings > Extensions and drag the file into that window.

Step 4. Connect WhatsApp Start a new chat in Claude and say: connect my WhatsApp A page with a QR code opens in your browser.

Step 5. Scan the QR On your phone: WhatsApp > Settings > Linked devices > Link a device (Android: the ⋮ menu > Linked devices). Scan the QR on the page. The QR changes by itself every 20 seconds or so; you don't need to refresh. When the page says Connected, you are done.

Step 6. Try it Back in Claude, ask: summarize my WhatsApp today

What you can ask

The settings page

Say open the WhatsApp settings page. It shows:

• Connection: connected or not, your number, since when

• Groups, Direct chats, Messages: how much is synced, and since which day

• Last update: the time of the newest message

• Last 7 days: one tile per day with the drops and how long each lasted

• Storage: how many days messages are kept, and the oldest one kept

And lets you change:

• Keep messages for: 7, 14, 30 (default) or 90 days. Older messages are deleted automatically.

• Country code: for local numbers that start with 0 (60 for Malaysia, 65 for Singapore, 44 for the UK). Leave it empty if you always use full numbers.

• Disconnect alerts: a desktop alert when WhatsApp is down for 3 minutes, or needs a new scan. Press Test alert to see one.

Voice notes and videos (optional)

Claude can see pictures by itself, but it can't hear voice notes or watch videos. Paste an API key on the settings page and it can.

1. Open the settings page (say open the WhatsApp settings page).

2. Under Voice notes and videos, paste the key and press Save key. It checks the key with Google or OpenAI first and only saves a working key.

3. With both keys saved, choose which one does voice notes under Voice notes with.

Good to know:

• Only the one file you ask about is sent, and only to the service whose key you saved.

• Each answer is kept (encrypted), so asking about the same file again costs nothing.

• The key is stored encrypted on your computer. The page shows only its last 4 characters.

• On Google's free tier, Google may use what you send to improve its products. A paid key avoids that.

• Using a key costs money on that service's account (usually very little per voice note).

Updating

• Claude Desktop: download the new whatsapp-mcp-desktop.mcpb from Releases and install it the same way. Your WhatsApp link and messages stay; no new scan.

• Claude Code: say "update WhatsApp MCP to the latest version: https://github.com/stevenpkm/whatsapp-mcp-desktop". Steps are in AGENTS.md.

Each Release lists the SHA-256 of the install file, so you or your agent can check the file is the real one.

When something goes wrong

Claude can read the log at <your user folder>/WhatsApp MCP/helper.log to explain a problem. The log never has message text.

Good to know

• Not official. It connects the way WhatsApp Web does (a linked device). WhatsApp does not allow unofficial apps, so a number can be banned. Read only is lower risk, but not zero. Use a second number if you can.

• Messages are written by other people. Claude is told never to follow instructions found in a message. Still, don't ask Claude to act on what a message says without checking it yourself.

• Only link your own number.

• When it receives messages. Installed in Claude Desktop: while Claude is open. Installed with Claude Code: in the background until the computer shuts down. After a gap, only recent messages come back.

• Where the data is. <your user folder>/WhatsApp MCP, encrypted. The key to open it is on the same computer, so anyone who can use this computer can read it.

• Files saved to Downloads are not encrypted.

• Nothing goes to the internet except WhatsApp itself, and Gemini or OpenAI only if you saved a key and asked about a voice note or video.

Remove it

1. Phone: WhatsApp > Linked devices > tap WhatsApp MCP > Log out

2. Claude > Settings > Extensions > remove WhatsApp (read only). Claude Code: claude mcp remove whatsapp

3. Delete the folder <your user folder>/WhatsApp MCP

For developers

• Node 22.5 or newer. npm install, then npm run selftest: builds the install file and runs every check with fake data and stand-ins for Gemini and OpenAI (no WhatsApp, no real keys).

• The install file is built to dist/whatsapp-mcp-desktop.mcpb. It holds two bundled JS files, no native parts, so one file works on Windows and Mac.

• src/index.ts: the program Claude starts. It only passes messages to src/helper.ts, which holds the WhatsApp connection, the database and the pages. The helper listens on 127.0.0.1 only, on a port the system picks; the pages need a random key in the link, and the MCP endpoint a token.

• WhatsApp engine: Baileys, pinned at 6.7.24.

• Developer and test settings: .env.example. Normal use needs none of them.

MIT License. Third-party licenses are listed in THIRD_PARTY_NOTICES.txt inside the install file. Not affiliated with WhatsApp, Meta, Google, OpenAI or Anthropic.