A customized WhatsApp MCP (Model Context Protocol) server for Amazon Quick Desktop — enabling AI assistants to read, search, and send WhatsApp messages (including media). Includes an auto-reply webhook powered by Amazon Bedrock Claude.
⚠️ Personal accounts only — uses the unofficial whatsmeow library (WhatsApp Web multidevice API). Not for WhatsApp Business. Meta may block unofficial access.
| Feature | Description |
|---|---|
| 🔍 Search & Read | Search contacts, list/filter messages, paginate chats |
| 📤 Send Messages | Text, images, videos, documents, voice messages |
| 🖼️ Media Download | Download media from any message |
| 🤖 Auto-Reply Webhook | Incoming messages trigger Bedrock Claude (text + vision) |
| 📱 Web QR Pairing | QR code displayed at http://localhost:8899 for easy phone linking |
| 🔊 Audio Conversion | Auto-converts audio to Opus OGG for WhatsApp voice messages |
# 1. Clone
git clone https://github.com/longlap/whatsapp-mcp.git
cd whatsapp-mcp
# 2. Run setup
bash setup.sh
# 3. Start the bridge and scan QR code
cd whatsapp-bridge && ./whatsapp-bridgeThen add the MCP config to Amazon Quick Desktop (Settings → Capabilities → MCP Servers).
See full instructions below.
┌─────────────────┐ stdio ┌──────────────────────┐
│ Amazon Quick │◄──────────────►│ Python MCP Server │
│ Desktop │ │ (whatsapp-mcp-server)│
└─────────────────┘ └──────────┬───────────┘
│ HTTP :8080
▼
┌──────────────────────┐
│ Go Bridge │
│ (whatsapp-bridge) │
│ + SQLite DB │
└──────────┬───────────┘
│ WhatsApp Web API
▼
┌──────────────────────┐
│ WhatsApp Servers │
└──────────────────────┘
| Tool | Required | Purpose |
|---|---|---|
| Go 1.21+ | ✅ | Build the WhatsApp bridge |
| Python 3.11+ | ✅ | Run the MCP server |
| uv | ✅ | Python package manager |
| Amazon Quick Desktop | ✅ | MCP client |
| FFmpeg | Optional | Audio conversion for voice messages |
| AWS CLI | Optional | Only for webhook auto-reply (Bedrock) |
cd whatsapp-bridge
go build -o whatsapp-bridgecd ../whatsapp-mcp-server
uv syncOr with pip:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtcd ../whatsapp-bridge
./whatsapp-bridgeScan the QR code with WhatsApp → Settings → Linked Devices → Link a Device.
Alternative: Run the QR web server for a nicer experience:
pip install qrcode
python3 qr_server.py
# Visit http://localhost:8899Settings → Capabilities → MCP Servers → Add:
{
"mcpServers": {
"whatsapp": {
"command": "/FULL/PATH/TO/whatsapp-mcp-server/.venv/bin/python",
"args": ["/FULL/PATH/TO/whatsapp-mcp-server/main.py"]
}
}
}| Tool | Description |
|---|---|
search_contacts |
Search contacts by name or phone number |
list_messages |
Get messages with filters (date, sender, chat, keyword) |
list_chats |
List chats sorted by activity |
send_message |
Send text to phone number or group JID |
send_file |
Send image/video/document |
send_audio_message |
Send voice message (auto-converts to Opus) |
download_media |
Download media from a message |
Uses Amazon Bedrock Claude to auto-reply to incoming messages (text + vision).
- Configure
webhook_listener.py— setALLOWED_JIDS,BEDROCK_MODEL,SYSTEM_PROMPT - Start:
./start_webhook.sh - Runs on port 9777
whatsapp-mcp/
├── whatsapp-bridge/ # Go bridge
│ ├── main.go
│ ├── go.mod / go.sum
│ └── qr_server.py # Web QR server (:8899)
├── whatsapp-mcp-server/ # Python MCP server
│ ├── main.py
│ ├── whatsapp.py
│ ├── audio.py
│ └── pyproject.toml
├── webhook_listener.py # Bedrock auto-reply
├── start_webhook.sh
├── setup.sh # One-command setup
└── README.md
| Issue | Solution |
|---|---|
| 405 error | Update whatsmeow: go get -u go.mau.fi/whatsmeow && go build |
| QR not showing | Restart bridge or use python3 qr_server.py |
| Messages not syncing | Delete store/*.db and re-link phone |
| Audio send fails | Install FFmpeg: brew install ffmpeg |
Based on lharries/whatsapp-mcp with custom enhancements:
- Webhook auto-reply with Bedrock Claude (text + vision)
- Web-based QR code pairing server
- Updated whatsmeow (June 2026)
MIT