WhatsApp over MCP

What this is

The Model Context Protocol is the standard way an AI client asks an outside system for information. Reply Wizard speaks it, so an assistant on your desktop can read the WhatsApp Web session already open in your browser, without a WhatsApp Business account, an API key or a phone-number registration.

A Chrome extension cannot be an MCP server on its own: it has no listening socket and no stdio. So there is one small companion process, published on npm as replywizard-whatsapp-mcp, which bridges the two ends. Your AI client launches it; you do not install it by hand.

AI client  ──MCP over stdio──▶  replywizard-whatsapp-mcp
                                        │
                            WebSocket on 127.0.0.1
                                        │
                                        ▼
                          Reply Wizard extension  ──▶  WhatsApp Web

Both hops are on 127.0.0.1. Nothing in this path reaches a server we run, and the bridge refuses every request until you have entered a pairing code in the extension.

What you need first

• Reply Wizard installed, in Chrome or another Chromium browser.
• WhatsApp Web open and logged in, in a tab. Every tool reads that live page, so a closed tab means no answer.
• Node.js 18 or later, because your client starts the bridge with npx.
• An AI provider configured in Reply Wizard, but only for the three tools that generate text. Reading your chats needs no provider at all.

Connect your AI client

The extension's WhatsApp MCP tab has one-click buttons for Cursor and VS Code, a copy button for the Claude Code command, and the raw configuration on screen beside them. An install deeplink is opaque by nature, so reading it first is always an option. The same configuration is written out here.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "replywizard": {
      "command": "npx",
      "args": ["-y", "replywizard-whatsapp-mcp"]
    }
  }
}

Claude Code

claude mcp add replywizard -- npx -y replywizard-whatsapp-mcp

Cursor and VS Code

Open the extension's WhatsApp MCP tab and press Add to Cursor or Add to VS Code. The editor receives exactly the configuration above.

Running from a clone instead

Point your client at node /absolute/path/to/mcp-host/src/connector.js after an npm install in that directory.

Use the single-argument npx -y replywizard-whatsapp-mcp form. The older -p <package> <bin> form fails to launch in some clients.

Pair it, once

Nothing runs until you type a six-digit code into the extension. That is the whole authorisation model: a process on your machine cannot read your WhatsApp until you have confirmed, in the browser, that you meant it.

1. Open WhatsApp Web in the browser that has Reply Wizard.
2. Open Reply Wizard's settings and go to the WhatsApp MCP tab. Turn on Enable AI access.
3. Start your AI client. It launches the bridge, which prints a six-digit pairing code and shows it as a desktop notification.
4. Type that code into the pairing field on the same tab, and press Pair.

Running the client in the background where you cannot see its log? The code is also written to ~/.replywizard-mcp/pairing-code.txt.

Once paired, the extension stores a session token and reconnects on its own. You will not be asked again. Revoke pairing, on the same tab, drops the token and closes the bridge.

A code lasts five minutes, survives a reconnect without being reissued, and is destroyed the moment it is used. Five wrong attempts lock it out, and reconnecting does not hand you five more.

Every tool, and what it takes

Eight tools. Five of them only read. Three generate text using the AI provider you have already configured in the extension, which is why they are listed separately: they are the ones that can cost you money at your own provider.

Reading

Generating

Chat and contact ids

An id from list_chats looks like 84726351928374@lid for a one-to-one chat or [email protected] for a group. WhatsApp has moved personal chats onto linked ids, which deliberately contain no phone number. A plain phone number in digits also resolves, for example 919110412164.

An id is matched exactly, or by its user part, or by phone number, in that order. There is no partial match on purpose: under linked-id addressing a substring can land on a different person's chat.

Things to ask for

You do not call tools by name. You ask, and the assistant picks.

• “Catch me up on the family group, I have not read it since Friday.”
• “What did Anita actually agree to in that thread?”
• “Find the address someone sent me last week.”
• “Which chats have I left unread the longest?”
• “Draft a polite decline to the last message, keep it two lines.”
• “Read me that voice note instead of making me listen to it.”

The last two produce text in your assistant. Sending it is still something you do yourself, in WhatsApp.

Several assistants at once

Claude Code, Cursor and Claude Desktop can share one WhatsApp session at the same time, and this needs no extra setup: the npx configuration above runs a small connector, which starts one shared daemon behind it.

client A ─┐
client B ─┼─▶ connector ─▶ daemon ⇄ Reply Wizard ⇄ WhatsApp Web
client C ─┘                (one daemon, many sessions)

A client that speaks HTTP can skip the connector and talk to the daemon directly, at http://127.0.0.1:7870/mcp, with a bearer token. The daemon writes that token to ~/.replywizard-mcp/daemon-token.json on first start, readable only by you. Delete the file to revoke it; the next start mints a new one.

The connector reads the token for you, so it never has to appear in your client's configuration.

Ports and environment variables

What it cannot do

There is no tool that sends, deletes, forwards or edits a WhatsApp message, and there is no combination of the eight above that adds up to one. The capability is absent from the protocol, not disabled by a setting.

• It cannot send a message, react, or mark anything as read.
• It cannot add, block or delete a contact, or leave a group.
• It cannot reach WhatsApp when your browser is closed. It reads the page you have open.
• It cannot read a message WhatsApp Web has not loaded. Scrollback is what the page is holding, not the full history.
• It cannot download media. A photo or a file is reported as one, not fetched.
• It cannot be reached from another machine. Both sockets are bound to 127.0.0.1.

Where your data goes

• To your AI client, on your machine. That is the point of the bridge, and it is the whole of the local path.
• To your AI provider, for the three generating tools only, using the key already in the extension. The bridge never sees that key: it forwards a request and receives a result.
• To us: nothing. We run no server in this path. There is nothing for us to receive.

The session token lives at ~/.replywizard-mcp/session.json, readable only by you. Revoking the pairing in the extension invalidates it immediately.

When something does not work

Ask your assistant to run ping first. It separates “the bridge is not there” from “the bridge is there and the answer is empty”, which are the two problems that look identical.

Still stuck? Send us the details and say which client you are using.