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
• Media: upload endpoints + /media hosting + MCP download tool

Quick Start (Docker)

# build and run

docker compose build

docker compose up -d

The server will be available at:

• Admin UI: http://localhost:3003/admin
• MCP endpoint: http://localhost:3003/mcp
• Media files: http://localhost:3003/media/<filename>

Runtime Settings

Settings can be edited in the admin UI and are persisted to SETTINGS_PATH (defaults to MEDIA_DIR/settings.json).

Supported settings:

• media_public_base_url
• upload_max_mb
• upload_enabled
• max_files_per_upload
• require_upload_token
• upload_token

Authentication

Built-in authentication is not implemented yet. In production, use a gateway that enforces auth. This project works well behind authmcp-gateway:

https://github.com/loglux/authmcp-gateway

Media Upload API

Base64 JSON:

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:<base64>}

Multipart (recommended for large files):

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

Both return url and (if configured) publicUrl.

Upload Auth (Optional)

If require_upload_token=true, provide a token with either:

• x-upload-token: <token>
• Authorization: Bearer <token>

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

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.

Messages

Tool	Description
list_messages	Get messages from a specific chat.
search_messages	Search messages by text (optionally scoped to a chat).
get_message_by_id	Get a specific message by ID (jid:id).
get_message_context	Get recent messages around a specific message.
get_last_interaction	Get the most recent message for a JID.
send_message	Send a text message to a person or group.

Media

Tool	Description
send_media	Send media (image/video/document/audio).
download_media	Download media from a message.

Utility

Tool	Description
ping	Health check tool.

License

MIT

Persistence

Chats and messages are persisted to a local SQLite database stored in the session volume.

Environment variables:

Variable	Default	Description
DB_PATH	<SESSION_DIR>/store.sqlite	SQLite database path for chats/messages persistence.

Export

Export a chat (JSON + optional downloaded media) via:

GET /api/export/chat/:jid?include_media=true

If include_media=true, the ZIP includes files already downloaded via download_media. It does not fetch missing media from WhatsApp.