whatsapp-mcp
A WhatsApp MCP server for Claude, built directly on whatsmeow. Encrypted at rest, prompt-injection-scrubbed, draft-and-confirm on every send, full audit trail, daily CI security gates. Actively maintained.
Why this one?
The most-starred WhatsApp MCP (lharries/whatsapp-mcp, 5.6K stars) is the architectural reference for this pattern, but has not shipped since July 2025 and leaves the lethal-trifecta problem entirely to the user. This implementation closes the gaps:
| Canonical | This implementation |
|---|
| Last shipped | July 2025 | Active |
| DB encryption | Plain SQLite | SQLCipher with key in macOS Keychain |
| Prompt-injection scrubber | None | Every inbound message |
| Send safety | Fires immediately | Mandatory confirm_send between draft and delivery |
| Audit log | None | Every tool call, 30-day retention |
| Voice notes | Not transcribed | whisper.cpp local, Spanish-tuned default |
| LID alias resolution | Open issue cluster upstream | Shipped, with backfill migration for legacy threads |
| CI security | None | govulncheck + pip-audit + Dependabot, daily |
Not a fork. The Go bridge is built directly against whatsmeow; the Python MCP layer and SQLite schema are original. Other implementations (lharries, LukasHaas, verygoodplugins) were read as reference only.
What this gives you
Claude can:
- Read your WhatsApp chats, messages, and contacts
- Search messages with accent-insensitive, typo-tolerant matching
- Transcribe voice notes locally via
whisper.cpp (Spanish-tuned by default)
- Resolve LID (Linked IDentifier) names instead of numeric placeholders
- Send text messages, reactions, and reply-quotes, with a mandatory
confirm_send step between draft and delivery
- Pull matching CRM context from your Obsidian vault when reading a chat
- See only prompt-injection-scrubbed message text, never raw adversarial input
Everything runs locally on your machine. No cloud sync. No telemetry. Optional OpenAI Whisper backend is opt-in, off by default.
Architecture
Two components, both local:
whatsapp-bridge/ (Go). Binds to 127.0.0.1 only. Wraps whatsmeow for the WhatsApp Web multidevice protocol. Owns SQLite persistence with SQLCipher encryption. Handles QR and pairing-code auth, media up/download, session recovery from StreamReplaced conflicts, call history capture. Exposes a REST API the Python MCP layer consumes.whatsapp-mcp-server/ (Python, FastMCP). Consumes the Go bridge REST API. Exposes 11 MCP tools to Claude: full read surface (chats, messages, contacts), accent-insensitive search, presence (typing, online, mark-read), and text-send + reactions + reply-quotes with mandatory confirm_send. Runs via uv and stdio transport.
Install
Open Claude Code, paste:
/plugin marketplace add adelaidasofia/whatsapp-mcp
/plugin install whatsapp-mcp@whatsapp-mcp
This installs the Python MCP server side. The Go bridge still needs the one-time QR pairing flow with your phone — see the legacy install block below for those steps.
Legacy install (manual, full Go bridge + QR pairing)
See SETUP.md for step-by-step install. In short:
- Prereqs: Go 1.24+, Python 3.11+, FFmpeg, uv
- Clone this repo
- Run
scripts/check_prerequisites.sh
- Start the bridge:
cd whatsapp-bridge && go run .
- Scan the QR code with WhatsApp on your phone (Settings, Linked Devices, Link a Device)
- Register the MCP in your Claude Code
.mcp.json
- Restart Claude Code
