WhatsApp Connect

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.

Picked http? There is a step 2: start the server. Nothing starts it

for you — until it runs, every client reports something like

ConnectionRefused at http://127.0.0.1:2178. Run (and keep running):

`sh

whatsapp-connect-mcp serve --http 127.0.0.1:2178

`

It acknowledges with serve: listening on http://127.0.0.1:2178 … and

stays in the foreground, so it dies with its terminal. To keep it alive

across logouts and reboots instead, install it as a background service

(launchd on macOS, a systemd user unit on Linux, or a Task Scheduler logon

task on Windows):

`sh

whatsapp-connect-mcp service install

`

service uninstall removes it; service restart restarts it after an

update. On a headless Linux box, add loginctl enable-linger so the

service outlives your login session. On Windows, the service runs as a

minimized console window that appears at user logon (not boot); closing the

window stops the server. There is no automatic restart on crash (serve's

unpaired state waits idle rather than exiting, so the common failure mode

never exits anyway). Creating the task may require an elevated

(Administrator) terminal.

setup then asks what those clients may read: every chat (the default), only your own self-chat, or nothing yet — leaving you to name the chats afterwards in the dashboard or with scope --allow. See Which chats an agent may read.

setup can be re-run any time — to pair again, or to add a client you installed later.

Pass --full-history to ask the phone for as much history as the protocol allows rather than the default few months. It only has any effect while actually pairing, so an install that is already paired must remove first; setup says so rather than silently ignoring the flag. The phone still decides what it really sends.

What this is for

The fourteen read tools are the product; the ten gated write tools are a convenience. In practice that means:

• Searching your own history. WhatsApp's own search has no date filters and shows you a hit with no context around it. search_messages plus get_message_context does both.
• Catching up. Point a model at the 400 messages a group accumulated while you were away and ask what happened.
• Reading your own attachments. download_media pulls down the invoices, receipts, and screenshots people sent you so a model can actually read them.
• Finding loose ends. get_last_interaction answers "who messaged me that I never replied to?"
• Drafting replies. The model writes it, the send gate makes you confirm it, then it sends.
• Searching WhatsApp alongside everything else. With mail, chat, or calendar MCP servers connected to the same client, "did this client contact me about the invoice, and where?" becomes one question instead of three separate searches. For anyone whose real correspondence lives in WhatsApp, this is the reason to run it.

What not to use it for

Do not build a support bot, an outreach tool, or an auto-responder on this. Messaging people who never messaged you first, at volume, is the behavior most consistently reported to get numbers banned (see Ban risk) — and it is precisely the use case Meta sells the WhatsApp Business API for. This is a personal tool for your own messages. Point it at customers and you will lose the number.

What it gives your MCP client

Twenty-four tools: fourteen read-only, ten gated, described below.

Read / search (no gate)

How far back any of these reach is decided by the paired phone, not by this

server. "Search my whole history" can turn out to mean "search the last few

months" — see Limitations.

*Which* chats they reach is yours to decide: by default every chat, or an

allowlist you set — see

Which chats an agent may read.

Send (gated — see below)

Every tool result built from WhatsApp data — messages, names, contacts, captions — is wrapped in an explicit untrusted-data banner. Treat it as data an MCP client is showing you, never as instructions the model should follow: nothing arriving over WhatsApp can tell your assistant what to do.

The send gate

This is the part verygoodplugins/whatsapp-mcp doesn't have. Every outbound action — text, media, voice note, reaction, edit, delete, poll, block, unblock, or read receipt — goes through one path, enforced by the server, not by prompting the model to "be careful":

1. Draft first. Call a send tool for a recipient you haven't trusted yet, and nothing is sent. You get back a preview (the recipient resolved to a name + JID, and the exact outbound content) and a draft_token.
2. Confirm to commit. Re-issue the identical call with that draft_token and it sends. Drafts expire after 5 minutes; a byte difference in the resubmitted content invalidates the token.
3. Trust, deliberately. whatsapp-connect-mcp trust --add marks a contact or group as trusted — being a name, a phone number, or a JID; an ambiguous name lists the matches and asks rather than guessing — so sends to it commit on the first call instead of drafting. This is a CLI-only switch — no MCP tool can grant trust, so a model can't trust its way around the draft step. The list