WhatsApp Connect MCP server

whatsapp-connect-mcp

A WhatsApp MCP server shipped as a single static Go binary. One download, one setup command, one QR scan — then any MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, …) can read, search, and send WhatsApp messages, with every outbound send protected by a server-enforced gate. That one-step path is the default stdio transport; the shared http transport adds one more step — a server you start and keep running (see Install).

**This uses an unofficial protocol. Read this before you pair a number you

care about.**

whatsapp-connect-mcp talks to WhatsApp the same way WhatsApp Web does, via

whatsmeow — not an official WhatsApp

Business API. Meta can and does ban numbers it detects using third-party

clients on this protocol, and such bans are widely reported as permanent.

The send gate and rate limiter described below cut the behavioral half of

that risk (accidental bulk sends, a model going rogue); **they cannot touch

the other half**, which is that this client is identifiable as a

third-party client at all. Ban risk lays out what the public

evidence actually shows, with dates. Pair a number you're comfortable

losing, not your only line to your bank or your family.

Status: pre-release.

Install (two minutes)

Pick one:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.ps1 | iex

# Anywhere with Node installed, no separate download step
npx whatsapp-connect-mcp setup
# or, sturdier for setup: a global install
npm install -g whatsapp-connect-mcp

npx whatsapp-connect-mcp serve works fine on its own, but for setup

prefer one of the install scripts above or the global install. setup

injects an absolute path to the running binary into each MCP client's

config, and under npx that path is inside npm's package cache — clear

that cache and every client config setup wrote now points at a binary

that's gone. A global install keeps the binary at a stable path until

the package itself is upgraded or removed.

Each of these downloads the release binary for your OS/architecture and runs setup: it shows a QR code to scan from WhatsApp (Linked Devices → Link a Device), then detects installed MCP clients and offers to inject a whatsapp server entry into whichever ones you pick. No toolchain, no manual JSON editing.

setup also asks how clients should connect. stdio (the default) has each client start its own server process — simplest, but only one client or session can be connected at a time, since one serve holds the data directory's exclusive lock. http points every selected client at one shared local server (http://127.0.0.1:, port of your choosing, default 2178, bearer-token authenticated) so several clients and sessions connect at once.

Shortened. The full README is on GitHub.