Content
# WhatsApp MCP Server (Custom Build)
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.
---
## Features
| 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 |
---
## Quick Start
```bash
# 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-bridge
```
Then add the MCP config to Amazon Quick Desktop (Settings → Capabilities → MCP Servers).
See full instructions below.
---
## Architecture
```
┌─────────────────┐ stdio ┌──────────────────────┐
│ Amazon Quick │◄──────────────►│ Python MCP Server │
│ Desktop │ │ (whatsapp-mcp-server)│
└─────────────────┘ └──────────┬───────────┘
│ HTTP :8080
▼
┌──────────────────────┐
│ Go Bridge │
│ (whatsapp-bridge) │
│ + SQLite DB │
└──────────┬───────────┘
│ WhatsApp Web API
▼
┌──────────────────────┐
│ WhatsApp Servers │
└──────────────────────┘
```
---
## Prerequisites
| 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) |
---
## Installation
### 1. Build the Go Bridge
```bash
cd whatsapp-bridge
go build -o whatsapp-bridge
```
### 2. Install Python Dependencies
```bash
cd ../whatsapp-mcp-server
uv sync
```
Or with pip:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 3. First Run — Link Your Phone
```bash
cd ../whatsapp-bridge
./whatsapp-bridge
```
Scan the QR code with WhatsApp → Settings → Linked Devices → Link a Device.
**Alternative**: Run the QR web server for a nicer experience:
```bash
pip install qrcode
python3 qr_server.py
# Visit http://localhost:8899
```
### 4. Configure Amazon Quick Desktop
Settings → Capabilities → MCP Servers → Add:
```json
{
"mcpServers": {
"whatsapp": {
"command": "/FULL/PATH/TO/whatsapp-mcp-server/.venv/bin/python",
"args": ["/FULL/PATH/TO/whatsapp-mcp-server/main.py"]
}
}
}
```
### 5. Restart Amazon Quick Desktop
---
## MCP Tools
| 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 |
---
## Auto-Reply Webhook (Optional)
Uses Amazon Bedrock Claude to auto-reply to incoming messages (text + vision).
1. Configure `webhook_listener.py` — set `ALLOWED_JIDS`, `BEDROCK_MODEL`, `SYSTEM_PROMPT`
2. Start: `./start_webhook.sh`
3. Runs on port 9777
---
## File Structure
```
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
```
---
## Troubleshooting
| 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` |
---
## Credits
Based on [lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) with custom enhancements:
- Webhook auto-reply with Bedrock Claude (text + vision)
- Web-based QR code pairing server
- Updated whatsmeow (June 2026)
## License
MIT
