WhatsApp MCP Extended

An extended Model Context Protocol (MCP) server for WhatsApp with 41 tools - advanced messaging, 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	41
Reactions	-	✅
Edit/Delete Messages	-	✅
Group Management	-	✅
Polls	-	✅
History Sync	-	✅
Presence/Online Status	-	✅
Newsletters	-	✅
Webhooks	-	✅
Custom Nicknames	-	✅

Architecture

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   whatsapp-bridge   │     │   whatsapp-mcp      │     │    webhook-ui       │
│   (Go + whatsmeow)  │◄────│   (Python + MCP)    │     │   (HTML/JS SPA)     │
│   Port: 8080        │     │   Ports: 8081,8082  │     │   Port: 8089        │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │
         ▼                           ▼
    ┌─────────────────────────────────────┐
    │           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 (41 Total)

Messaging

Tool	Description
send_message	Send text message
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)

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
get_direct_chat_by_contact	Find DM with contact
get_contact_chats	All chats involving contact
get_last_interaction	Most recent message with contact
request_history	Request older message history

Contacts

Tool	Description
search_contacts	Search by name/phone
list_all_contacts	List all contacts
get_contact_details	Full contact info
set_nickname	Set custom nickname
get_nickname	Get custom nickname
remove_nickname	Remove nickname
list_nicknames	List all nicknames

Groups

Tool	Description
get_group_info	Group metadata & participants
create_group	Create new group
add_group_members	Add members
remove_group_members	Remove members
promote_to_admin	Promote to admin
demote_admin	Demote admin
leave_group	Leave group
update_group	Update name/topic
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
block_user	Block user
unblock_user	Unblock user

Newsletters (Channels)

Tool	Description
follow_newsletter	Follow channel
unfollow_newsletter	Unfollow channel
create_newsletter	Create new channel

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 webhook UI at http://localhost:8089

Development

Manual Setup

# Bridge (Go 1.24+)
cd whatsapp-bridge && go run main.go

# MCP Server (Python 3.11+)
cd whatsapp-mcp-server && uv sync && uv run python main.py

# Webhook UI
cd whatsapp-webhook-ui && python3 -m http.server 8089

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	SSE transport
Gradio UI	8082	Web testing UI
Webhook UI	8089	Webhook management

Troubleshooting

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

docker-compose logs -f whatsapp-bridge
# Scan QR with WhatsApp mobile app

Credits

Fork chain:

• lharries/whatsapp-mcp - Original MCP server (12 tools)
• AdamRussak/whatsapp-mcp - Added webhooks, container split, webhook UI
• This repo - Added reactions, edit/delete, groups, polls, presence, newsletters (41 tools)

Libraries:

• whatsmeow - Go WhatsApp Web API
• FastMCP - Python MCP SDK

License

MIT License - see LICENSE file.