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.

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

npx whatsapp-connect-mcp serve works fine on its own, but for setup prefer one of the install scripts above. 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.

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>, port of your choosing, default 2178, bearer-token authenticated) so several clients and sessions connect at once — the trade-off being that you start that server yourself with whatsapp-connect-mcp serve --http 127.0.0.1:<port> and clients can only connect while it is running.

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.

Related MCP server: WhatsApp Business API MCP Server

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.

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 <jid> marks a contact or group as trusted, 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. A running serve process reads the trust list once at startup, so a change takes effect the next time serve starts, not immediately. For the running session there is a lighter-weight grant: whatsapp-connect-mcp trust --session --add <jid> elevates a recipient for the life of the current serve process only — it takes effect immediately, is never written to config.json, and is wiped automatically the next time serve starts. Use it when you are actively drafting a thread with one person or group and have already confirmed the first sends by hand; it cuts the draft-and-confirm round-trip for that recipient without granting anything permanent. Like persistent trust it is CLI-only (no MCP tool can grant it), and block/unblock still draft on every call regardless.

4. Rate limit, always. Every send — drafted, trusted, whatever — consumes a token from one rate limiter shared across all five send tools. The interval has a hard 5-second floor that no configuration can go below. A rate-limited commit leaves the draft valid; retry the same call with the same token once the limit clears.

mark_read is the one exception to drafting: a read receipt isn't authored content, so it always sends on the first call (still rate-limited, still gated).

Which files a send may attach

The gate above authorises a recipient. It says nothing about the file a send names, so on its own it would let a manipulated model attach anything this program can read — an SSH key, a password store — to a recipient you had already trusted.

So outbound files are confined to an allowlist of directories. The default is a single dedicated one, created on first run:

Move a file there before sending it, or widen the list by setting media_roots in config.json to absolute directory paths:

{ "media_roots": ["/home/you/Pictures", "/home/you/Documents"] }

Paths are resolved before they are checked, so a symlink inside an allowed directory is judged by where it actually leads, not where it sits. A send naming a file outside the list is refused on the first call — before a draft is minted and before it costs a rate-limit token — and the refusal names no path, like every other error this server returns.

Comparison with verygoodplugins/whatsapp-mcp

The current best-known alternative works, but is painful to adopt and has no send safety:

Ban risk

Meta detects third-party clients in two independent ways, and only one of them is behavior.

1. The client is identifiable. A linked device announces itself when it registers. whatsmeow's defaults announce an OS string of whatsmeow with an unknown platform type, which is distinguishable from an official client by reading the pairing payload alone. This project overrides that and announces a Chrome browser identity instead (internal/bridge/bridge.go), which is also what your phone shows for this device under Linked Devices.

Do not mistake that override for a fix. It defeats the most trivial version of the check and not the underlying problem. serve and setup do refresh the reported WhatsApp Web version before connecting, so the version and the build hash derived from it track a real release rather than whichever one was vendored at build time — but the user agent still carries whatsmeow's placeholder carrier and manufacturer fields, and the session behaves on the wire like whatsmeow, not like Chrome. Users of whatsapp-web.js — which drives a real Chrome browser with a genuine fingerprint — received the same warnings described below, which suggests the announced identity was never the deciding signal. Changing it also does nothing for a session that is already paired: the identity is sent when pairing, so an existing session keeps whatever it registered with until you pair it again.

2. Behavior. Reported triggers, roughly by how often they come up: messaging people who never messaged you first, high send velocity, volume soon after pairing, the same message sent repeatedly, automated Status posts, and noisy reconnection loops.

The uncomfortable part is that the public evidence points at (1) as the dominant factor. In whatsmeow#810 — the May 2025 "your account may be at risk" wave, closed not planned in July 2026 — users report the warning on accounts that were idle and merely connected, having never sent a message, and on accounts that had been disconnected for weeks. Users of whatsapp-web.js, an entirely different implementation, received it too. A Baileys maintainer in that same thread argues the opposite, that it is "mostly a behavioral issue." Nobody established which, and the thread was closed without an answer.

So: the send gate and rate limiter here are real mitigations for (2) and do nothing for (1). On the available evidence, behaving well affects when your turn comes rather than whether it comes.

Reports worth reading before you pair, dated so you can judge how current they are:

Treat ban statistics from vendor blogs — "68% of businesses banned within 12 months", "a rolling 30-day no-reply threshold" — as unsourced marketing from paid Business API resellers. No primary source supports them, and neither number appears in this document for that reason.

Limitations (stated plainly)

• Your number can be banned, and this project cannot prevent it. See Ban risk. This is the limitation that matters most.

• History depth is phone-decided. Like every WhatsApp Web client, the paired phone controls how much chat history syncs to this server. There is no setting here that fetches more than the phone hands over. setup --full-history asks for as much as the protocol allows instead of the default few months, but it is a request, not a setting — and it only applies when pairing. For an install that is already paired, the fetch_older_messages tool asks the phone for more of a single chat without re-pairing. Both are requests the phone is free to answer with less, or nothing; neither recovers messages the phone itself has deleted.

• Voice notes need Ogg Opus input. send_voice_note does no transcoding. If your source audio isn't already .ogg/Opus, convert it first (e.g. ffmpeg -i in.mp3 -c:a libopus out.ogg).

• No outbound calls. Call history is readable; initiating a call is not supported.

• One paired number per install. Multi-account isn't supported in v1.

• whatsmeow tracks WhatsApp protocol changes, not the other way around. A WhatsApp-side change can break pairing or sending until whatsmeow (and in turn this project) catches up.

Data and privacy

Everything — session keys, messages, media, contacts, call log — lives in a local SQLite database under this program's data directory. Nothing about your messages, contacts, or media is sent anywhere by this server.

Exactly two outbound network calls exist beyond the WhatsApp connection itself. Both are best-effort, both time out after 2 seconds, and neither carries message content, a JID, a phone number, or any session credential:

• doctor/check asks GitHub's public release API whether a newer version of this program exists. It never blocks or fails the check when GitHub is unreachable.

• serve and setup fetch the current WhatsApp Web client version from web.whatsapp.com before connecting, so the version this client reports tracks a real release instead of whichever one was vendored at build time. A failure is reported and ignored; a stale version still connects.

The data directory:

Diagnostics

whatsapp-connect-mcp check

Runs the same checks the doctor MCP tool exposes: session pairing/connect state, event-flow liveness (a connected session that has received no WhatsApp events for over 30 minutes gets a warning — the state where the socket looks healthy but ingestion has silently stalled), message database integrity, injected MCP client configs, data directory permissions (POSIX), and the version check above. Every finding is sanitized — no JID, phone number, message content, or filesystem path ever appears in a status line; a broken client config is named by the client's name, never its path on disk.

Other commands

whatsapp-connect-mcp setup [--full-history]  # pair (again) and configure MCP clients
whatsapp-connect-mcp status                  # pairing state, row counts, injected clients
whatsapp-connect-mcp clients [--remove]      # list or uninject MCP client entries
whatsapp-connect-mcp trust [--session] [--add jid|--remove jid|--list]
whatsapp-connect-mcp serve [--http addr]     # run the MCP server directly (stdio by default)

--http requires a bearer token and a loopback Host. On first use it generates a 256-bit token, writes it to .http-token in the data directory (owner-only), and prints it once — put it in your client's Authorization: Bearer <token> header. Every request must also be addressed to a loopback Host (localhost, 127.0.0.1, [::1]), which blocks a web page in your browser from reaching the server by rebinding DNS to a loopback address. Still bind 127.0.0.1: the token guards against reaching the port, but binding a public interface exposes it to your whole network, and if you must, put your own access control (a reverse proxy, a VPN, a firewall rule) in front.

Uninstall / reset

• whatsapp-connect-mcp remove deletes the local WhatsApp session (unpairs this server from it locally — the next setup requires pairing again). This is local-only: it does not notify WhatsApp's servers, so your phone keeps showing this device as linked under Linked Devices until you unlink it there yourself. Prompts for a typed yes before doing anything.

• whatsapp-connect-mcp reset does everything remove does, plus deletes stored messages, media, and settings — a full wipe back to a fresh install. Also prompts for a typed yes.

• whatsapp-connect-mcp clients --remove uninjects this program's entry from any MCP client config it was added to, without touching the paired session.

• To remove the binary itself, delete it from wherever the installer put it (~/.local/bin, %LOCALAPPDATA%\Programs\whatsapp-connect-mcp, or wherever npx cached it) and delete the data directory listed above.

License

MIT — see LICENSE.