WhatsApp MCP
Gives an AI agent read and send access to a personal WhatsApp account by linking as a WhatsApp Web multidevice client. Exposes 86 MCP tools spanning messages (read, search, send, edit, delete, recover, reply, react, polls, contact cards, locations, voice-note transcription, scheduled messages), Statuses/Stories (list, view, post, delete, viewers), profile (About text, profile photo, contact metadata), presence and typing indicators, groups (create, leave, join via link, participants, name, topic, invite link), channels, a bridge-local contacts address book, blocklist and privacy settings, plus an auto-responder and audit/metrics endpoints, with message history cached in a local SQLite database.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
WhatsApp MCP
A self-hosted Model Context Protocol (MCP) server that gives an AI agent read and send access to your personal WhatsApp account. It runs on your machine as a single Go binary, speaks MCP over Streamable HTTP at 127.0.0.1:8765/mcp, and keeps your message history in a local SQLite database.
This is an independent, community project. It is not affiliated with, endorsed by, or operated by Meta Platforms, Inc. or WhatsApp LLC.
What it does
Once paired with your phone (the same way you link WhatsApp Web), the daemon:
Domain | What it does |
Messages | Read, search, send, edit, delete, and recover messages; read receipts; mark read; schedule messages; reply; react; poll; contact cards; locations; voice-note transcription |
Statuses (Stories) | Read, view, post, delete statuses; read receipts; status privacy setting |
Profile | Read/set About text, profile photo, contact metadata (About, verified name, LID, linked devices) |
Presence | Query contact online/last-seen; set per-chat typing/recording indicators |
Groups | Create, leave, join via link, participants, name, topic, announce, lock, invite link |
Channels | Follow/unfollow, mute, list, info, messages |
Contacts | Local address book (bridge-only; not synced to the phone), search, create, update, delete |
Blocklist & Privacy | Blocklist, privacy settings (group add, last seen, status, profile, read receipts, online, calls, messages, defense, stickers) |
Scheduling | Timer-driven scheduled messages that survive restarts |
Auto-responder | Event-driven out-of-office replies to incoming 1:1 text messages |
Audit & observability | Audit log, health check, Prometheus metrics, WebSocket events, SSE pairing events |
The daemon exposes 86 MCP tools over Streamable HTTP, serves health (/healthz) and Prometheus metrics (/metrics), and pushes new messages to connected clients over WebSocket (/ws/events).
Related MCP server: wa-bridge
Architecture
┌─────────────────┐ Streamable HTTP ┌─────────────────────┐
│ AI agent │◄─────────────────────────►│ whatsapp-mcp │
│ (Claude, etc.) │ /mcp │ MCP server (Go) │
└─────────────────┘ │ • 86 tool handlers │
│ • rate limiting │
│ • SQLite cache │
└──────────┬──────────┘
│
│ whatsmeow multidevice
│ protocol (vendored fork)
▼
┌─────────────────────┐
│ WhatsApp Web │
│ (linked device) │
│ phone ↔ server │
└─────────────────────┘The daemon wraps whatsmeow, the Go WhatsApp Web multidevice library. Because WhatsApp changes its protocol server-side without notice, the project vendors whatsmeow via a Go replace directive and applies protocol fixes immediately rather than waiting for upstream:
replace go.mau.fi/whatsmeow => ./vendor-whatsmeow/go.mau.fi/whatsmeowProtocol fixes carried in the fork (also contributed upstream where applicable):
Fix | What it does |
SKDM group ID |
|
Profile picture tctoken | Media requests include the required token so thumbnails resolve |
Presence subscribe | Missing |
Argo decoding | Hard-coded failure and macOS early-return removed |
SendPresence race | Presence updates no longer race with session teardown |
GetPrivacySettings | Errors are no longer swallowed |
set_status_message | WhatsApp Web calls the |
canonicalContactJID | Wrong suffix |
Quick start
Prerequisites
Go 1.26+ (build-time only; runtime needs just the compiled binary)
FFmpeg (optional, for voice-note transcoding via
send_audio_message)An MCP client that speaks HTTP (Claude Desktop, Cursor, Claude Code, OpenCode, etc.)
Build
Download a prebuilt binary from the latest release. Release assets cover Linux (amd64, arm64), macOS (amd64, arm64) and Windows (amd64), with SHA-256 sums in checksums.txt. The binary needs no runtime dependencies except FFmpeg for voice-note transcoding.
Or build from source:
git clone https://github.com/muhammedanasmithadi/whatsapp-mcp.git
cd whatsapp-mcp
make build # writes ./bin/whatsapp-mcpPair your phone
Start the daemon, then open the pairing page:
./bin/whatsapp-mcp serve # starts on 127.0.0.1:8765Visit http://127.0.0.1:8765/pair, scan the QR code with WhatsApp (Settings → Linked Devices → Link a Device), and the session persists to ./store/whatsapp.db. WhatsApp rotates the session roughly every 20 days; the daemon re-pairs automatically with exponential backoff.
No browser? Run ./bin/whatsapp-mcp login to render the QR in the terminal, or use the phone-number form on /pair.
Connect your MCP client
Add this to your client configuration:
// OpenCode (opencode.jsonc), Claude Code, Cursor, etc.
{
"mcpServers": {
"whatsapp": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}Restart your client. The daemon outlives client restarts.
One-click install with MCPB
Each release also ships a .mcpb bundle for Linux, macOS and Windows. Install the bundle matching your platform in an MCPB-capable desktop client; the client starts the binary over stdio and fills in the configuration for you.
Pair once before installing the bundle, because stdio mode has no browser to show a QR code:
whatsapp-mcp -store ~/.whatsapp-mcp loginThe bundle's store_dir setting defaults to ~/.whatsapp-mcp, and its read_only setting maps to WHATSAPP_MCP_READ_ONLY. To run stdio mode by hand:
whatsapp-mcp -store ~/.whatsapp-mcp stdio -read-onlystdout carries JSON-RPC frames only; every diagnostic goes to stderr.
Serve flags and environment
Flag / env var | Default | Purpose |
|
| HTTP bind address |
| off | Bind to a non-loopback address (requires |
| — | Bearer token for |
| off | Expose only read/query tools (no send, edit, delete, mark-read, group, blocklist, privacy, status-change tools) |
|
|
|
|
| File allowlist root for send/download tools |
|
| Name shown for this device in WhatsApp → Linked Devices |
| off | Backfill older messages for all cached chats after pairing |
| off | Verbose (unredacted) logs |
Observability
GET /healthz— JSON:connected,paired,state,uptime_secGET /metrics— Prometheus text format: messages in/out, sends, errors, rate-limited, pairing state, uptime
Real-time push
WS /ws/events— WebSocket broadcast of new-message events as JSONGET /pair/events— Server-Sent Events stream of pairing state transitions
MCP tools reference
The server exposes 86 tools, grouped by domain:
Messaging
Tool | Description |
| Send a text message to a person or group |
| Upload and send a picture, video, document, or attachment |
| Send an audio file as a voice note (transcodes via ffmpeg if needed) |
| Send a map location |
| Send a contact card (vCard) |
| Send a poll with 2–32 options |
| Cast a vote on a poll |
| Add or replace an emoji reaction on a message |
| Send a reply that quotes a previous message |
| Edit the text of a sent message |
| Revoke (delete) a sent message |
| Request WhatsApp to re-send media for a message |
| Transcribe a voice note via the configured STT endpoint |
| Send multiple messages in one call |
Statuses (Stories)
Tool | Description |
| List cached Status updates grouped by sender |
| Send read receipts for a contact's statuses |
| Post a Status update (image/video + caption) |
| Delete one of your own status updates |
| Viewers of a status (WhatsApp does not expose this to linked devices; returns empty list with a note) |
| Set who can see your statuses ( |
Profile & presence
Tool | Description |
| Live profile metadata (About, profile-picture ID, LID, devices, business verification) |
| Fetch a contact's or group's profile photo |
| Set the paired account's profile photo |
| Set the About text shown in the profile |
| Query a contact's online/last-seen state |
| Show or hide per-chat typing/recording indicator |
| Set global online/offline availability |
Groups
Tool | Description |
| Create a group with participants |
| Leave a group |
| Join a group via invite link |
| Get group metadata |
| Get or reset a group invite link |
| Rename a group |
| Set group topic/description |
| Set announce-only mode |
| Lock/unlock a group |
| Add/remove/promote/demote participants |
| Mute/unmute a chat |
| Pin/unpin a chat in the chat list |
Channels
Tool | Description |
| List followed WhatsApp Channels |
| Follow a channel |
| Unfollow a channel |
| Mute/unmute a channel |
| Get channel metadata |
| List messages from a channel |
Contacts
Tool | Description |
| List local address-book contacts |
| Create a local contact entry |
| Update a local contact |
| Delete a local contact |
| Search contacts by name or phone |
| Check if phone numbers are registered on WhatsApp |
Blocklist & privacy
Tool | Description |
| List blocked contacts |
| Block a contact |
| Unblock a contact |
| Read privacy settings |
| Set a privacy setting ( |
Scheduling
Tool | Description |
| Queue a text message for later delivery (timer-driven, survives restarts) |
| Cancel a pending scheduled message |
| List queued messages with status |
Auto-responder
Tool | Description |
| Enable/disable automatic replies to incoming 1:1 text messages |
| Read current auto-responder configuration |
Chat management
Tool | Description |
| Mute/unmute a chat |
| Pin/unpin a chat |
| Archive/unarchive a chat |
| Set disappearing-message timer |
| Star/unstar a message |
History & queries
Tool | Description |
| List cached chats |
| List messages in a chat |
| List chats by label |
| Get context around a message |
| Get chat metadata |
| List messages with media |
| Download media for a message |
| Search contacts |
| Read/set read position in a chat |
| Mark messages as read |
| Mark read position |
Pairing & audit
Tool | Description |
| Return pairing state |
| Return audit-log entries |
Statuses (Stories) — push-only delivery, recoverable via re-pair
Status updates arrive as push broadcasts while the daemon is online and paired. There is no on-demand server fetch for statuses on an already-paired device — WAWebApiStatus.getAllStatuses reads from local cache only.
Missing statuses can be recovered by re-pairing. When a linked device pairs for the first time, WhatsApp sends INITIAL_STATUS_V3 (history sync type 1) which carries recent status updates. The daemon imports HistorySync.statusV3Messages (field 3) into status@broadcast rows, resolves the poster via key.participant / WebMessageInfo.participant (LID → phone number), and keeps placeholders for pruned payloads.
To recover statuses posted while the daemon was offline:
Log out the MCP device from your phone (WhatsApp → Linked Devices → "WhatsApp MCP" → Log out)
Restart the daemon:
systemctl --user restart whatsapp-mcp.serviceScan the fresh QR code at
http://127.0.0.1:8765/pairDuring pairing bootstrap, WhatsApp sends
INITIAL_STATUS_V3and the daemon caches recent statuses automatically
Profile photos and online/last-seen presence work independently of status delivery.
Safety
This tool connects an AI agent to your personal WhatsApp account. Treat it accordingly:
Loopback only by default. The daemon binds to
127.0.0.1. Do not expose it remotely withoutWHATSAPP_MCP_TOKEN.Read-only mode. Run with
-read-onlyif you only need the agent to read and summarize chats. It strips every send, edit, delete, mark-read, group, blocklist, privacy, and status-change tool.Untrusted input. Incoming message text is data fed to an LLM. Prompt injection could exfiltrate chat history. Do not assume message content is safe.
Contacts did not consent. Their messages to you enter the agent's context window and go to the model provider.
Media
WHATSAPP_MCP_MEDIA_ROOT (default <store>/uploads/) is the only directory send/download tools may touch. Paths outside the root, including symlinks that resolve outside it, are rejected.
Operations
systemd (Linux)
The project includes a systemd user unit at docs/systemd/whatsapp-mcp.service. Install it:
mkdir -p ~/.config/systemd/user
cp docs/systemd/whatsapp-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now whatsapp-mcp.servicelaunchd (macOS)
A launchd plist is provided at docs/launchd/com.sealjay.whatsapp-mcp.plist.
Webhooks
The daemon optionally verifies /webhook/ signatures using WHATSAPP_WEBHOOK_SECRET.
Development
make build # writes ./bin/whatsapp-mcp
make test # unit tests
make test-race # with -race
make test-cover # coverage report
make vet # go vet
make fmt # gofmt check
make lint # vet + fmt
make smoke # boot-test without connecting to WhatsApp
make e2e # end-to-end tests (requires paired daemon)
make upgrade-check # bump go.mau.fi/whatsmeow, re-tidy, build, testPair for integration testing
./bin/whatsapp-mcp loginThere is no offline fixture for whatsmeow sessions; integration testing requires a real paired WhatsApp account.
Contributing
Open an issue before starting non-trivial work so we can agree on scope.
One logical change per pull request. Keep diffs focused and reviewable.
Match existing code style in Go (
cmd/,internal/).Do not commit
.envfiles, database files (*.db), session state, or media.Do not re-add
.claude/ordocs/superpowers/— those were removed from the repo.If you add a new tool, update
expectedToolNamesand the tool count ininternal/mcp/tools_test.go.If you add a new env var or serve flag, document it in
README.mdunder "Serve flags and environment".
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
WhatsApp MCP on your own number: read chats, search contacts, send messages.
Related MCP Servers
- AlicenseAqualityAmaintenanceSingle-binary Go MCP server that wraps whatsmeow to expose a personal WhatsApp account as MCP tools (messaging, groups, polls, media, privacy).4324MIT
- AlicenseNot gradedqualityCmaintenanceA self-hosted WhatsApp bridge that exposes a stdio MCP server with ~20 tools for reading conversations, sending messages, managing groups, contacts, and aliases, enabling AI agents to operate WhatsApp directly.4MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted WhatsApp management over Model Context Protocol, exposing a streamable HTTP MCP endpoint with 30 tools for session/QR pairing, messaging, media storage, and optional on-CPU voice note transcription via whisper.cpp.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for WhatsApp that exposes send, read, and media management tools through the waxum REST API gateway, enabling any MCP client to interact with WhatsApp chats and media over stdio.2MIT