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)

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

Chats & Messages

Contacts

Groups

Presence & Profile

Newsletters (Channels)

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

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.