replywizard-whatsapp-mcp

Local Model Context Protocol server that exposes your WhatsApp Web session to AI clients (Claude Desktop, Claude Code, Cursor, …) through the Reply Wizard Chrome extension.

v1 is read + value only and local-only: there is no path that can send or modify WhatsApp messages, and nothing leaves your machine.

How it works

A Chrome extension cannot itself be an MCP server (no listening socket / stdio). So this is a small companion process that bridges two connections:

AI client  ──MCP over stdio──▶  replywizard-whatsapp-mcp  ──WebSocket (127.0.0.1)──▶  Reply Wizard extension  ──▶  WhatsApp Web

• The AI client speaks MCP to this process over stdio.
• This process runs a WebSocket server on 127.0.0.1:7869; the extension dials in as a client.
• Each tools/call is forwarded to the extension, executed against the WhatsApp page, and returned.

This package is intentionally self-contained (only @modelcontextprotocol/sdk and ws) so it can be lifted into its own repository without touching the extension.

Tools

| Tool | Kind | What it does | |------|------|--------------| | ping | health | Confirms the extension is connected and a WhatsApp Web tab is reachable. | | list_chats | read | Recent chats: id, name, isGroup, unreadCount, timestamp. | | get_messages | read | Recent (loaded) messages for a chat; media is labelled, voice notes report duration. | | get_contact | read | Look up one contact by id. | | list_contacts | read | Your saved (address-book) contacts. | | summarize_chat | value | Bulleted summary of a chat's recent messages (uses your configured AI provider). | | suggest_reply | value | Drafts a reply as you — returns text only, never sends. | | transcribe_voice_note | value | Transcribes a voice note via your configured cloud speech-to-text provider. |

Value tools reuse the extension's existing AI/STT configuration; your API keys never leave the extension (the hub only sees tool arguments and results).

Setup

Multi-agent by default. The npx -y replywizard-whatsapp-mcp config below runs the connector (the package's default bin), which auto-starts a shared local daemon — so several assistants (Claude Code + Cursor + Claude Desktop, …) can share one WhatsApp session at once, with no extra setup. See Multiple AI assistants at once for the architecture. Use the single-arg form above (not the older -p <pkg> <bin> form, which some clients fail to launch).

Published to npm as replywizard-whatsapp-mcp. You don't install anything by hand — your AI client runs it via npx (requires Node.js 18+).

Claude Desktop

Add to claude_desktop_config.json:

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

Claude Code

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

RW_MCP_PORT is optional (defaults to 7869); set it on both sides if you change it.

Running from source instead? Clone the repo, cd mcp-host && npm install, and point your client at node /absolute/path/to/mcp-host/src/connector.js (multi-agent) — or node .../src/index.js for the legacy single-client, no-daemon hub.

Multiple AI assistants at once (daemon)

This happens automatically with the npx config above: replywizard-whatsapp-mcp runs the connector, which starts one shared daemon. (The legacy index.js hub — run directly via node .../src/index.js — binds the WebSocket port itself, so only one AI client can use it at a time; a second launch hits EADDRINUSE.) The daemon architecture:

client A (HTTP) ─┐
client B (stdio)→ rw-mcp-connector ─┤→ rw-mcp-daemon  ⇄  Reply Wizard extension  ⇄  WhatsApp Web
client C (stdio)→ rw-mcp-connector ─┘   (one daemon; owns ws://127.0.0.1:7869, serves http://127.0.0.1:7870/mcp)

• rw-mcp-daemon — long-lived; owns the extension WebSocket and serves MCP over Streamable HTTP to any number of clients (each gets its own session). Single-instance: a second daemon exits cleanly.
• rw-mcp-connector — a stdio shim for clients that only launch a command; it auto-starts the daemon if needed and transparently proxies. Reads the auth token for you (no token in your config).

Clients that speak HTTP (e.g. Claude Code) connect to the daemon directly — no connector needed:

TOKEN=$(node -e "console.log(require('os').homedir())")/.replywizard-mcp/daemon-token.json   # see the token
claude mcp add rw --transport http http://127.0.0.1:7870/mcp --header "Authorization: Bearer <token>"

Stdio-only clients use the connector (auto-token, auto-start):

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

From source: node /abs/path/mcp-host/src/connector.js (or …/daemon.js to run the daemon directly).

Environment variables

| Var | Default | Meaning | |-----|---------|---------| | RW_MCP_PORT | 7869 | Extension WebSocket port. | | RW_MCP_HTTP_PORT | 7870 | Daemon HTTP (client) port. | | RW_MCP_IDLE_MS | 1800000 | Daemon exits after this long with no sessions (0 disables). | | RW_MCP_STALE_SESSION_MS | 600000 | Reap sessions silent this long (client crashed without a clean disconnect). |

Auth token

The daemon generates a bearer token on first start at ~/.replywizard-mcp/daemon-token.json (mode 600). Every /mcp request must present it (Authorization: Bearer <token>); /healthz is open. The connector reads it automatically. To revoke, delete that file (the daemon mints a new one on next start) — existing clients must pick up the new token.

First-run pairing

1. Open WhatsApp Web in the browser with Reply Wizard installed.
2. Click the Reply Wizard toolbar icon → AI client access → Enable AI access.
3. Start your AI client (it launches this hub). The hub prints a 6-digit pairing code to its stderr / the client's MCP log.
4. Enter that code in the extension popup. Once paired, the extension stores a session token and reconnects automatically on subsequent runs (no code needed again).

Use Revoke access in the popup to drop the token and disable the bridge.

Security

• Binds to 127.0.0.1 only.
• No tool runs until the pairing code is confirmed in the extension.
• Read + value tools only — v1 has no send/modify capability.
• The session token is stored at ~/.replywizard-mcp/session.json (mode 600).

Troubleshooting

| Symptom | Fix | |---------|-----| | Reply Wizard extension is not connected | Open WhatsApp Web and enable AI access in the popup. | | Not paired yet | Enter the 6-digit code (printed to the hub's stderr) in the popup. | | No WhatsApp Web tab is open | A read/value tool needs an open, logged-in WhatsApp Web tab. | | Transcription error about a cloud provider | transcribe_voice_note needs a cloud STT key in Options → Speech-to-Text (on-device STT is not used over MCP). | | Port in use | The default is 7869. Changing it is advanced (set RW_MCP_PORT on the hub and the rw_mcp_port value in the extension's storage to match). |

See ../docs/MCP_EXECUTION_PLAN.md and ../docs/MCP_INTEGRATION_IMPLEMENTATION_PLAN.md.