whatsapp-mcp

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:

1. Prereqs: Go 1.24+, Python 3.11+, FFmpeg, uv
2. Clone this repo
3. Run scripts/check_prerequisites.sh
4. Start the bridge: cd whatsapp-bridge && go run .
5. Scan the QR code with WhatsApp on your phone (Settings, Linked Devices, Link a Device)
6. Register the MCP in your Claude Code .mcp.json
7. Restart Claude Code