WhatsApp MCP Extended

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 lharries/whatsapp-mcp (original). Extended with reactions, message editing, polls, group management, presence, newsletters, and more.

What's New (vs Original)

Feature	Original	Extended
MCP Tools	12	26 default / 15 lean
Reactions	-	✅
Edit/Delete Messages	-	✅
Group Management	-	✅
Polls	-	✅
History Sync	-	✅
Presence/Online Status	-	✅
Newsletters	-	✅
Webhooks	-	✅
Custom Nicknames	-	✅

Architecture

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   whatsapp-bridge   │     │   whatsapp-mcp      │     │   whatsapp-web-ui   │
│   (Go + whatsmeow)  │◄────│   (Python + MCP)    │     │   (HTML/JS SPA)     │
│   Port: 8080        │     │   Port: 8081        │     │   Port: 8090        │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │
         ▼                           ▼
    ┌─────────────────────────────────────┐
    │           SQLite (store/)           │
    │  messages.db │ whatsapp.db          │
    └─────────────────────────────────────┘

Quick Start

Docker (Recommended)

git clone https://github.com/felixisaac/whatsapp-mcp-extended
cd whatsapp-mcp-extended

docker network create n8n_n8n_traefik_network
docker-compose up -d

# Scan QR code to authenticate
docker-compose logs -f whatsapp-bridge

Claude Desktop / Cursor Integration

Add to your MCP config (claude_desktop_config.json or Cursor settings):

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/whatsapp-mcp-extended/whatsapp-mcp-server", "python", "main.py"]
    }
  }
}

MCP Tools

Version 0.2.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.

Migration:

Prefer	Replaces
get_contact_context	get_contact_details, get_direct_chat_by_contact, get_contact_chats, get_last_interaction
manage_nickname	set_nickname, get_nickname, remove_nickname, list_nicknames
manage_group	create_group, add_group_members, remove_group_members, promote_to_admin, demote_admin, leave_group, update_group
get_blocklist, manage_blocklist	get_blocklist, block_user, unblock_user
manage_newsletter	follow_newsletter, unfollow_newsletter, create_newsletter

Messaging

| Tool | Description |

... View full README on GitHub