loglux/whatsapp-mcp-stream

A WhatsApp MCP server built around **Streamable HTTP** transport, using **Baileys** for WhatsApp connectivity, with a web admin UI and bidirectional media flow (upload + download).
Key points:
- Transport: Streamable HTTP at /mcp
- Engine: Baileys
- Admin UI: QR, status, logout, runtime settings, chat history viewer
- Media: upload endpoints + /media hosting + MCP download tool
Quick Start (Docker)
The server will be available at:
- Admin UI: http://localhost:3003/admin
- MCP endpoint: http://localhost:3003/mcp
- Media files: http://localhost:3003/media/
DNS on hosts with --iptables=false
On some NAS / hardened hosts (e.g. Synology with dockerd --iptables=false), Docker's embedded DNS proxy (127.0.0.11) has no iptables DNAT rules and refuses connections inside containers.
Fix: copy resolv.conf.example to resolv.conf and add a volume override:
Then add to a local docker-compose.override.yml (not committed):
docker compose up picks up the override automatically.
Runtime Settings
Settings can be edited in the admin UI and are persisted to SETTINGS_PATH (defaults to MEDIA_DIR/settings.json).
Admin UI
*Admin console with runtime settings, QR linking, chat history viewer, export, and status.*
Supported settings:
- media_public_base_url
- upload_max_mb
- upload_enabled
- max_files_per_upload
- require_upload_token
- upload_token
- auto_download_media
- auto_download_max_mb
Authentication
Built-in authentication is not implemented yet. In production, use a gateway that enforces auth. This project works well behind authmcp-gateway:
Media Upload API
Base64 JSON:
Multipart (recommended for large files):
Both return url and (if configured) publicUrl.
Sending Local Files via send_media
The ./files/ directory in the project root is bind-mounted into the container at /app/files. Drop any file there and reference it immediately — no container restart needed:
For a URL source, pass media_url directly to send_media or stage_media — the server downloads the file itself without base64.
Upload Auth (Optional)
If require_upload_token=true, provide a token with either:
- x-upload-token:
- Authorization: Bearer
MCP Transport
The server exposes Streamable HTTP at /mcp.
Typical flow:
1. POST /mcp with JSON-RPC initialize
2. Use the returned mcp-session-id header for subsequent requests
3. POST /mcp for tool calls
Note: clients must send Accept: application/json, text/event-stream on initialize.
Smoke Test
Quick regression smoke for MCP tools:
Optional custom target:
MCP Tools
Auth
| Tool | Description |
| --- | --- |
| get_qr_code | Get the latest WhatsApp QR code as an image for authentication. |
| check_auth_status | Check if the WhatsApp client is authenticated and ready. |
| logout | Logout from WhatsApp and clear the current session. |
Contacts
| Tool | Description |
| --- | --- |
| search_contacts | Search contacts by name or phone number. |
| resolve_contact | Resolve a contact by name or phone number (best matches). |
| get_contact_by_id | Get contact details by JID. |
| get_profile_pic | Get profile picture URL for a JID. |
| get_group_info | Get group metadata and participants by group JID. |
Chats
| Tool | Description |
| --- | --- |
| list_chats | List chats with metadata and optional last message. |
| get_chat_by_id | Get chat metadata by JID. |
| list_groups | List group chats only. |
| get_direct_chat_by_contact_number | Resolve a direct chat JID by phone number. |
| get_chat_by_contact | Resolve a contact by name or phone number and return chat metadata. |
| analyze_group_overlaps | Find members that appear across multiple groups. |
| find_members_without_direct_chat | Find group members with no direct chat. |
| find_members_not_in_contacts | Find group members missing from contacts. |