Read, search, and send personal WhatsApp messages from any MCP client, behind a send-confirm gate.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
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:
npx whatsapp-connect-mcp serveworks fine on its own, but forsetupprefer one of the install scripts above or the global install.setupinjects an absolute path to the running binary into each MCP client's config, and undernpxthat path is inside npm's package cache — clear that cache and every client configsetupwrote 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>, 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):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):
service uninstallremoves it;service restartrestarts it after an update. On a headless Linux box, addloginctl enable-lingerso 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 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_messagesplusget_message_contextdoes 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_mediapulls down the invoices, receipts, and screenshots people sent you so a model can actually read them. - Finding loose ends.
get_last_interactionanswers "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)
| Tool | What it returns |
|---|---|
list_chats | Chats (1:1 and group), newest activity first; filterable by name and archived state. |
get_chat | One chat by JID. |
list_messages | Messages in a chat, newest first, optionally time-bounded — pass a named window (today, yesterday, last_24h, last_7d) or a date with an IANA tz, or explicit bounds (Unix seconds, RFC 3339, or a bare date); the server does the timezone arithmetic. |
search_messages | Full-text search over message bodies, chat-scoped or global. |
get_message_context | The messages immediately before/after one target message. |
search_contacts | Contacts by name or phone number substring. |
get_last_interaction | The most recent message involving a JID. |
list_group_participants | A group's member JIDs, fetched live. |
get_group_info | A group's subject, description, owner, and admins, fetched live. |
get_blocklist | The JIDs the account has blocked, fetched live. |
get_call_history | Calls, newest first, optionally filtered to one peer and time-bounded with the same window/date/tz forms as list_messages. |
download_media | Downloads attached media to the local data directory — one message, a batch of message ids, or everything in a time window (same window/date/tz forms as list_messages, optionally filtered by kind). |
poll_new_messages | New messages after a cursor, oldest first — tail: N returns the newest N immediately, and a timeout blocks up to 240s until one arrives, so an agent can react to activity without re-reading chats. Own sends excluded unless asked for. Read-only; reacting still goes through the send gate. |
fetch_older_messages | Asks the phone for messages from before the oldest one stored in a chat, widening how far back it can be read. Call repeatedly to page further back. |
doctor | Runs the diagnostics described in Diagnostics as an MCP tool. |
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)
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about WhatsApp Connect
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/whatsapp-connect)HTML Embed
<a href="https://allmcps.com/mcp/whatsapp-connect"><img src="https://allmcps.com/api/badge/whatsapp-connect?style=directory" alt="WhatsApp Connect on AllMCPs" /></a>