{"id":"4de2ee89-2251-4d4e-be78-376b38903659","slug":"whatsapp-mcp-extended","kind":"mcp","name":"whatsapp-mcp-extended","summary":"Actively maintained WhatsApp MCP — 26 tools, webhooks, anti-ban, Docker, self-healing. Drop-in for abandoned lharries/whatsapp-mcp.","owner":"FelixIsaac","repoUrl":"https://github.com/FelixIsaac/whatsapp-mcp-extended","license":"MIT","licenseTier":"permissive","trust":"community","stars":39,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-12-24T13:44:55.000Z","addedAt":"2026-10-14T05:16:21.211Z","logoUrl":"https://avatars.githubusercontent.com/u/38658663?u=27665e3e7bb0a21159ebc980a5fe1fb7684bf894&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","cloud-infra","memory-knowledge"],"tags":["ai","claude","whatsapp","whatsmeow","ai-agent","automation","docker","fastmcp"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-15T03:01:12.788Z","sample":false,"url":"https://conduits.dev/tools/whatsapp-mcp-extended","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# WhatsApp MCP Extended\n\nAn 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.\n\n> Built on [AdamRussak/whatsapp-mcp](https://github.com/AdamRussak/whatsapp-mcp) (webhooks, containers) which forked [lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) (original). Extended with reactions, message editing, polls, group management, presence, newsletters, and more.\n\n![WhatsApp MCP](./example-use.png)\n\n## What's New (vs Original)\n\n| Feature | Original | Extended |\n|---------|----------|----------|\n| MCP Tools | 12 | **26 default / 15 lean** |\n| Reactions | - | ✅ |\n| Edit/Delete Messages | - | ✅ |\n| Group Management | - | ✅ |\n| Polls | - | ✅ |\n| History Sync | - | ✅ |\n| Presence/Online Status | - | ✅ |\n| Newsletters | - | ✅ |\n| Webhooks | - | ✅ |\n| Custom Nicknames | - | ✅ |\n\n## Architecture\n\n```\n┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐\n│   whatsapp-bridge   │     │   whatsapp-mcp      │     │   whatsapp-web-ui   │\n│   (Go + whatsmeow)  │◄────│   (Python + MCP)    │     │   (HTML/JS SPA)     │\n│   Port: 8080        │     │   Port: 8081        │     │   Port: 8090        │\n└─────────────────────┘     └─────────────────────┘     └─────────────────────┘\n         │                           │\n         ▼                           ▼\n    ┌─────────────────────────────────────┐\n    │           SQLite (store/)           │\n    │  messages.db │ whatsapp.db          │\n    └─────────────────────────────────────┘\n```\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\ngit clone https://github.com/felixisaac/whatsapp-mcp-extended\ncd whatsapp-mcp-extended\n\ndocker network create n8n_n8n_traefik_network\ndocker-compose up -d\n\n# Scan QR code to authenticate\ndocker-compose logs -f whatsapp-bridge\n```\n\n### Claude Desktop / Cursor Integration\n\nAdd to your MCP config (`claude_desktop_config.json` or Cursor settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/whatsapp-mcp-extended/whatsapp-mcp-server\", \"python\", \"main.py\"]\n    }\n  }\n}\n```\n\n### Security & Safety Gate (Allowlist)\n\nTo 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`:\n\n```bash\n# Allow sending only to specific phone numbers or group JIDs (comma-separated)\nWHATSAPP_ALLOWLIST_JIDS=1234567890,9876543210@s.whatsapp.net,1203630123456789@g.us\n```\n\n## MCP Tools\n\nVersion `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.\n\nDefault toolsets:\n\n```bash\nWHATSAPP_MCP_TOOLSETS=all\n```\n\nLean recommended toolsets:\n\n```bash\nWHATSAPP_MCP_TOOLSETS=core,send,media\n```\n\nToolsets:\n\n| Toolset | Default | Tools |\n|---------|---------|-------|\n| `core` | Yes | Search/read tools, contact context, group info, profile picture |\n| `send` | Yes | `send_message`, `send_reaction`, `create_poll` |\n| `media` | Yes | `send_file`, `send_audio_message`, `download_media` |\n| `history` | No | `request_history` |\n| `contacts_write` | No | `manage_nickname` |\n| `message_admin` | No | `edit_message`, `delete_message`, `mark_read` |\n| `groups` | No | `manage_group` |\n| `presence` | No | `set_presence`, `subscribe_presence` |\n| `account_admin` | No | `get_blocklist`, `manage_blocklist` |\n| `newsletter` | No | `manage_newsletter` |\n\nYou can also expose individual tools with `WHATSAPP_MCP_TOOLS=manage_group,delete_message`.\n\nBreaking change in `0.2.0`: older narrow tools are no longer exposed to the agent. Use the merged replacements below.\n\nMigration:\n\n| Prefer | Replaces |\n|--------|----------|\n| `get_contact_context` | `get_contact_details`, `get_direct_chat_by_contact`, `get_contact_chats`, `get_last_interaction` |\n| `manage_nickname` | `set_nickname`, `get_nickname`, `remove_nickname`, `list_nicknames` |\n| `manage_group` | `create_group`, `add_group_members`, `remove_group_members`, `promote_to_admin`, `demote_admin`, `leave_group`, `update_group` |\n| `get_blocklist`, `manage_blocklist` | `get_blocklist`, `block_user`, `unblock_user` |\n| `manage_newsletter` | `follow_newsletter`, `unfollow_newsletter`, `create_newsletter` |\n\n### Messaging\n| Tool | Description |\n|------|-------------|\n| `send_message` | Send text message (supports optional `quoted_message_id` to reply/quote) |\n| `send_file` | Send image/video/document |\n| `send_audio_message` | Send voice message |\n| `download_media` | Download received media |\n| `send_reaction` | React to message with emoji |\n| `edit_message` | Edit sent message |\n| `delete_message` | Delete/revoke message |\n| `mark_read` | Mark messages as read (blue ticks), or as played for voice messages (`receipt_type=\"played\"`) |\n\n### Chats & Messages\n| Tool | Description |\n|------|-------------|\n| `list_chats` | List all chats |\n| `get_chat` | Get chat by JID |\n| `list_messages` | Search messages with filters |\n| `get_message_context` | Get messages around a specific message |\n| `request_history` | Request older message history |\n\n### Contacts\n| Tool | Description |\n|------|-------------|\n| `search_contacts` | Search by name/phone |\n| `list_all_contacts` | List all contacts |\n| `get_contact_context` | Full contact info, related chats, and last interaction |\n| `manage_nickname` | Set/get/remove/list custom nicknames |\n\n### Groups\n| Tool | Description |\n|------|-------------|\n| `get_group_info` | Group metadata & participants |\n| `manage_group` | Create/update/leave groups and manage members/admins |\n| `create_poll` | Create poll in chat |\n\n### Presence & Profile\n| Tool | Description |\n|------|-------------|\n| `set_presence` | Set online/offline status |\n| `subscribe_presence` | Subscribe to contact's presence |\n| `get_profile_picture` | Get profile picture URL |\n| `get_blocklist` | List blocked users |\n| `manage_blocklist` | Block/unblock users |\n\n### Newsletters (Channels)\n| Tool | Description |\n|------|-------------|\n| `manage_newsletter` | Follow, unfollow, or create channels |\n\n## Design Philosophy: Lean Transport Primitives\n\n`whatsapp-mcp-extended` is engineered according to the **Unix Philosophy**:\n* **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).\n* **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.\n\n### 🔌 Plugins & Extensions\n\nReference plugins and recipes are available in the [`plugins/`](plugins/) directory:\n- **`plugins/transcribe_voice_notes.py`**: Local voice note transcription using `mlx-whisper` or Whisper.\n- **`plugins/semantic_recall.py`**: Multilingual semantic search over message history using `sentence-transformers`.\n- **All-in-One Fork:** Users looking for a pre-packaged ML bundle can check out [@simonseifert's fork](https://github.com/simonseifert/whatsapp-mcp-pro).\n\nResponse data prioritizes **complete context with minimal interpretation**. See [METADATA_PHILOSOPHY.md](./docs/METADATA_PHILOSOPHY.md) for:\n\n- Why we include raw data instead of pre-computed signals\n- How we reduce token waste for consuming LLMs\n- Response structure examples (Messages, Chats, Contacts)\n- Design rules: raw facts, countable metrics, exclude nulls\n\n**TL;DR:** Get all contact info in one response instead of repeated queries. LLM infers tone, urgency, relationships from raw data + metrics.\n\n## Webhook System\n\nReal-time HTTP webhooks for incoming messages with:\n- **Triggers**: all, chat_jid, sender, keyword, media_type\n- **Matching**: exact, contains, regex\n- **Security**: HMAC-SHA256 signatures\n- **Retry**: Exponential backoff\n\nAccess the web UI at `http://localhost:8090`\n\n## Development\n\n### Manual Setup\n\n```bash\n# Bridge (Go 1.25+)\ncd whatsapp-bridge && go run main.go\n\n# MCP Server (Python 3.11+)\ncd whatsapp-mcp-server && uv sync && uv run python main.py\n\n# Web UI\ncd whatsapp-web-ui && npm install && npm run dev\n```\n\n### Pre-build Checks\n\n```bash\ncd whatsapp-mcp-server\nuv run python check.py  # Catches errors before docker build\n```\n\n### Updating whatsmeow\n\nWhen you see `Client outdated (405)` errors:\n\n```bash\ncd whatsapp-bridge\ngo get -u go.mau.fi/whatsmeow@latest\ngo mod tidy\ndocker-compose build whatsapp-bridge\ndocker-compose up -d whatsapp-bridge\n```\n\n## Ports\n\n| Service | Port | Description |\n|---------|------|-------------|\n| Bridge API | 8080 (→8180) | REST API |\n| MCP Server | 8081 | Streamable HTTP transport |\n| Web UI | 8090 | Chat, contacts, and webhook management |\n\n## Configuration\n\nEnvironment variables for the bridge (set in `.env` or `docker-compose.yaml`):\n\n| Variable | Default | Description |\n|---|---|---|\n| `API_KEY` | *(required)* | Bearer token for all authenticated API calls |\n| `PRESENCE_PING_ENABLED` | `true` | Set `false` to stop broadcasting \"online\" to contacts |\n| `PRESENCE_PING_INTERVAL` | `20m` | How often to ping presence. Accepts Go duration strings (`20m`, `1h`). Keep ≥20m to avoid bot fingerprinting |\n| `HISTORY_SYNC_DAYS_LIMIT` | `365` | Days of history to sync on first link |\n| `HISTORY_SYNC_SIZE_MB` | `5000` | Max history sync size |\n| `STORAGE_QUOTA_MB` | `10240` | Device storage quota |\n| `API_PORT` | `8080` | Bridge HTTP port (internal) |\n\n## Quick Commands\n\nAfter running `setup.ps1` once, use the Makefile for day-to-day operations:\n\n```bash\nmake status          # check connection state (connected, needs_pairing, jid)\nmake pair PHONE=+60123456789   # pair via 8-digit phone code — no QR scan needed\nmake pairing-status  # check pairing code progress\nmake pair-reset      # reset pairing state if previous attempt timed out\nmake reconnect       # force reconnect (no re-pairing)\nmake logs            # tail bridge logs\nmake sync-venv       # re-sync Python venv (fix missing module errors)\nmake open-ui         # open web UI in browser (QR scan, webhooks, contacts)\n```\n\n## Session Reliability\n\n**Session lifetime rules** (WhatsApp-enforced, cannot be changed):\n- Primary phone must connect to WhatsApp at least every **14 days**\n- The bridge companion device must be active at least every **30 days**\n- WebSocket idle disconnects after ~30 min (auto-reconnects, no re-pairing needed)\n\n**What causes permanent logout** (requires re-scanning QR):\n- Phone offline >14 days\n- Manual unlink from phone (Settings → Linked Devices)\n- WhatsApp detects suspicious activity / protocol fingerprinting\n- WhatsApp app update that forces re-authentication\n\n**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](https://developers.facebook.com/docs/whatsapp/cloud-api) is the only compliant path.\n\n**If the bridge goes unhealthy** (needs re-pairing):\n\n```bash\nmake status          # check: needs_pairing=true means re-pair required\nmake pair PHONE=+60123456789   # preferred: 8-digit code, no QR scan\n# or: open http://127.0.0.1:8090 and scan QR\n```\n\nYou can also configure a webhook to receive `logged_out` events so you're alerted immediately when the session is revoked.\n\n## Troubleshooting\n\n### Bridge needs re-pairing after restart\n\nThe 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`.\n\n### Messages Not Delivering\n\nIf API returns success but messages show single checkmark:\n\n```bash\ndocker-compose restart whatsapp-bridge\ndocker-compose logs --tail=10 whatsapp-bridge\n# Should see: \"✓ Connected to WhatsApp!\"\n```\n\n### QR Code Issues\n\n```bash\n# Option 1: phone number code (no QR scan needed)\nmake pair PHONE=+60123456789\n\n# Option 2: scan QR via web UI\nopen http://127.0.0.1:8090\n\n# Option 3: terminal QR\ndocker-compose logs -f whatsapp-bridge\n```\n\n### MCP server fails to start (missing module)\n\n```bash\nmake sync-venv   # re-runs uv sync in whatsapp-mcp-server/\n```\n\n### Check bridge health\n\n```bash\ncurl http://127.0.0.1:8180/api/health\n# connected: true/false\n# needs_pairing: true means QR/code scan required (not just a reconnect)\n# disconnected_for: how long it's been offline\n```\n\n## Credits\n\n**Fork chain:**\n- [lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) - Original MCP server (12 tools)\n- [AdamRussak/whatsapp-mcp](https://github.com/AdamRussak/whatsapp-mcp) - Added webhooks, container split, webhook UI\n- This repo - Added reactions, edit/delete, groups, polls, presence, newsletters, and a curated MCP tool surface\n\n**Libraries:**\n- [whatsmeow](https://github.com/tulir/whatsmeow) - Go WhatsApp Web API\n- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP SDK\n\n### Community Acknowledgements\n\nSeveral forks independently solved real problems and their ideas have been incorporated into this repo. Credit where it's due:\n\n| Contributor | What they figured out |\n|---|---|\n| [simonseifert](https://github.com/simonseifert) | Optional on-device voice transcription (`mlx-whisper`) & multilingual semantic search (`sentence-transformers`); `direct_path` DB column tracking for CDN fallback; inline `Image` content blocks |\n| [bitterdev](https://github.com/bitterdev) | WhatsApp LID addressing resolution (`GetAltJID()`), mapping `<id>@lid` recipients to phone JIDs to prevent server error 463 |\n| [domdomegg](https://github.com/domdomegg) | Security scan workflow fixes and `.gitleaks.toml` allowlist configuration |\n| [laudite](https://github.com/laudite/whatsapp-mcp-extended) | Media captions in `ExtractTextContent()`; quoted/reply context in webhooks; `@mention` auto-detection |\n| [kasperpeulen](https://github.com/kasperpeulen/whatsapp-mcp-extended) | Contact name resolution priority chain (`FullName > PushName > FirstName > Business`) |\n| [Coriatel](https://github.com/Coriatel/whatsapp-mcp-extended) | First working `/api/download` implementation with manual HKDF/AES-CBC decryption |\n| [jedijashwa](https://github.com/jedijashwa/whatsapp-mcp-extended) | Reactions silently failing fix (wrong sender JID lookup); extended MIME type support |\n| [slarrain](https://github.com/slarrain/whatsapp-mcp-extended) | LID JID normalization — diagnosed conversation-splitting bug |\n\nIf you've forked this repo and built something useful, open a PR or issue — good ideas deserve to flow upstream.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n"}