An extended Model Context Protocol (MCP) server for WhatsApp with a toolset-gated, agent-facing surface for messaging, search, media, group management, webhooks, presence, and more.
Built on AdamRussak/whatsapp-mcp (webhooks, containers) which forked (original). Extended with reactions, message editing, polls, group management, presence, newsletters, and more.
To restrict outgoing message delivery to a specified set of allowed contacts or groups (useful for dev environments or enterprise privacy gates), set WHATSAPP_ALLOWLIST_JIDS:
# Allow sending only to specific phone numbers or group JIDs (comma-separated)
WHATSAPP_ALLOWLIST_JIDS=1234567890,[email protected],[email protected]
MCP Tools
Version 0.4.0 exposes the full curated MCP surface by default for compatibility. Users who want a leaner agent context can opt into smaller toolsets.
Default toolsets:
WHATSAPP_MCP_TOOLSETS=all
Lean recommended toolsets:
WHATSAPP_MCP_TOOLSETS=core,send,media
Toolsets:
Toolset
Default
Tools
core
Yes
Search/read tools, contact context, group info, profile picture
send
Yes
send_message, send_reaction, create_poll
media
Yes
send_file, send_audio_message, download_media
history
No
request_history
contacts_write
No
manage_nickname
message_admin
No
edit_message, delete_message, mark_read
groups
No
manage_group
presence
No
set_presence, subscribe_presence
account_admin
No
get_blocklist, manage_blocklist
newsletter
No
manage_newsletter
You can also expose individual tools with WHATSAPP_MCP_TOOLS=manage_group,delete_message.
Breaking change in 0.2.0: older narrow tools are no longer exposed to the agent. Use the merged replacements below.
Send text message (supports optional quoted_message_id to reply/quote)
send_file
Send image/video/document
send_audio_message
Send voice message
download_media
Download received media
send_reaction
React to message with emoji
edit_message
Edit sent message
delete_message
Delete/revoke message
mark_read
Mark messages as read (blue ticks), or as played for voice messages (receipt_type="played")
Chats & Messages
Tool
Description
list_chats
List all chats
get_chat
Get chat by JID
list_messages
Search messages with filters
get_message_context
Get messages around a specific message
request_history
Request older message history
Contacts
Tool
Description
search_contacts
Search by name/phone
list_all_contacts
List all contacts
get_contact_context
Full contact info, related chats, and last interaction
manage_nickname
Set/get/remove/list custom nicknames
Groups
Tool
Description
get_group_info
Group metadata & participants
manage_group
Create/update/leave groups and manage members/admins
create_poll
Create poll in chat
Presence & Profile
Tool
Description
set_presence
Set online/offline status
subscribe_presence
Subscribe to contact's presence
get_profile_picture
Get profile picture URL
get_blocklist
List blocked users
manage_blocklist
Block/unblock users
Newsletters (Channels)
Tool
Description
manage_newsletter
Follow, unfollow, or create channels
Design Philosophy: Lean Transport Primitives
whatsapp-mcp-extended is engineered according to the Unix Philosophy:
Do One Thing Well: Be a rock-solid, production-grade transport layer to WhatsApp (socket lifecycle, messaging CRUD, media downloads, reactions, group administration, webhooks, and safety allowlists).
Composable Primitives: High-level AI features (voice-to-text transcription, vector database semantic recall, LLM summarizers) are kept modular. whatsapp-mcp-extended returns clean, raw media file paths (download_media) and message arrays (list_messages) so AI agents (Claude Code, Cursor, OpenCode, Codex) can chain them with specialized sidecars or plugins.
🔌 Plugins & Extensions
Reference plugins and recipes are available in the plugins/ directory:
plugins/transcribe_voice_notes.py: Local voice note transcription using mlx-whisper or Whisper.
plugins/semantic_recall.py: Multilingual semantic search over message history using sentence-transformers.
All-in-One Fork: Users looking for a pre-packaged ML bundle can check out @simonseifert's fork.
Response data prioritizes complete context with minimal interpretation. See METADATA_PHILOSOPHY.md for:
Why we include raw data instead of pre-computed signals
Design rules: raw facts, countable metrics, exclude nulls
TL;DR: Get all contact info in one response instead of repeated queries. LLM infers tone, urgency, relationships from raw data + metrics.
Webhook System
Real-time HTTP webhooks for incoming messages with:
Triggers: all, chat_jid, sender, keyword, media_type
Matching: exact, contains, regex
Security: HMAC-SHA256 signatures
Retry: Exponential backoff
Access the web UI at http://localhost:8090
Development
Manual Setup
# Bridge (Go 1.25+)
cd whatsapp-bridge && go run main.go
# MCP Server (Python 3.11+)
cd whatsapp-mcp-server && uv sync && uv run python main.py
# Web UI
cd whatsapp-web-ui && npm install && npm run dev
Pre-build Checks
cd whatsapp-mcp-server
uv run python check.py # Catches errors before docker build
Updating whatsmeow
When you see Client outdated (405) errors:
cd whatsapp-bridge
go get -u go.mau.fi/whatsmeow@latest
go mod tidy
docker-compose build whatsapp-bridge
docker-compose up -d whatsapp-bridge
Ports
Service
Port
Description
Bridge API
8080 (→8180)
REST API
MCP Server
8081
Streamable HTTP transport
Web UI
8090
Chat, contacts, and webhook management
Configuration
Environment variables for the bridge (set in .env or docker-compose.yaml):
Variable
Default
Description
API_KEY
(required)
Bearer token for all authenticated API calls
PRESENCE_PING_ENABLED
true
Set false to stop broadcasting "online" to contacts
PRESENCE_PING_INTERVAL
20m
How often to ping presence. Accepts Go duration strings (20m, 1h). Keep ≥20m to avoid bot fingerprinting
HISTORY_SYNC_DAYS_LIMIT
365
Days of history to sync on first link
HISTORY_SYNC_SIZE_MB
5000
Max history sync size
STORAGE_QUOTA_MB
10240
Device storage quota
API_PORT
8080
Bridge HTTP port (internal)
Quick Commands
After running setup.ps1 once, use the Makefile for day-to-day operations:
make status # check connection state (connected, needs_pairing, jid)
make pair PHONE=+60123456789 # pair via 8-digit phone code — no QR scan needed
make pairing-status # check pairing code progress
make pair-reset # reset pairing state if previous attempt timed out
make reconnect # force reconnect (no re-pairing)
make logs # tail bridge logs
make sync-venv # re-sync Python venv (fix missing module errors)
make open-ui # open web UI in browser (QR scan, webhooks, contacts)
Session Reliability
Session lifetime rules (WhatsApp-enforced, cannot be changed):
Primary phone must connect to WhatsApp at least every 14 days
The bridge companion device must be active at least every 30 days
WebSocket idle disconnects after ~30 min (auto-reconnects, no re-pairing needed)
What causes permanent logout (requires re-scanning QR):
Phone offline >14 days
Manual unlink from phone (Settings → Linked Devices)
Account risk: This is a third-party bridge using an unofficial API. Use a dedicated non-personal number. WhatsApp has been aggressively detecting and banning automation tools since 2025. For business-critical use, the WhatsApp Business API is the only compliant path.
If the bridge goes unhealthy (needs re-pairing):
make status # check: needs_pairing=true means re-pair required
make pair PHONE=+60123456789 # preferred: 8-digit code, no QR scan
# or: open http://127.0.0.1:8090 and scan QR
You can also configure a webhook to receive logged_out events so you're alerted immediately when the session is revoked.
Troubleshooting
Bridge needs re-pairing after restart
The bridge stores credentials in store/whatsapp.db. If that file exists but the bridge still shows QR, WhatsApp revoked the session server-side (check your phone → Settings → Linked Devices). Re-pair using make pair PHONE=+60... or open http://127.0.0.1:8090.
Messages Not Delivering
If API returns success but messages show single checkmark:
docker-compose restart whatsapp-bridge
docker-compose logs --tail=10 whatsapp-bridge
# Should see: "✓ Connected to WhatsApp!"
QR Code Issues
# Option 1: phone number code (no QR scan needed)
make pair PHONE=+60123456789
# Option 2: scan QR via web UI
open http://127.0.0.1:8090
# Option 3: terminal QR
docker-compose logs -f whatsapp-bridge
MCP server fails to start (missing module)
make sync-venv # re-runs uv sync in whatsapp-mcp-server/
Check bridge health
curl http://127.0.0.1:8180/api/health
# connected: true/false
# needs_pairing: true means QR/code scan required (not just a reconnect)
# disconnected_for: how long it's been offline