WhatsApp MCP Stream

This WhatsApp MCP Stream server provides a Streamable HTTP MCP endpoint for WhatsApp connectivity, backed by Baileys, with an admin UI and bidirectional media handling. It lets you initialize a WhatsApp session, manage contacts and chats, and upload or download media through a unified MCP interface.

How to use

You interact with the MCP server through the Streamable HTTP endpoint exposed at the /mcp path. Start a session by sending an initialize request, receive a session identifier, and then perform tool calls to manage contacts, chats, messages, and media. Use the admin UI to monitor status, manage runtime settings, and view the current QR authentication state.

How to install

Prerequisites: you need Docker and Docker Compose installed on your machine.

# build and run using Docker
docker compose build

docker compose up -d

Additional information

Configuration and persistence are handled through settings and a local SQLite database stored in the session volume. The admin UI is available at the admin path, and media can be uploaded or downloaded through the provided media endpoints.

Security is not implemented in the server itself for authentication. In production, place the MCP behind an authentication gateway to enforce access control.

Configuration and endpoints

Key endpoints you will use include the MCP transport path and media hosting. The MCP API is reachable at the following HTTP endpoint in a typical local setup.

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

Export and media handling

Export a chat to JSON with optional media included. Media can be downloaded via the media endpoints, and media uploads are supported through dedicated upload APIs.

Available tools

get_qr_code

Retrieve the latest WhatsApp QR code image for authentication.

check_auth_status

Check whether the WhatsApp client is authenticated and ready.

logout

Logout from WhatsApp and clear the current session.

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.

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.

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.

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.

send_media

Send media (image/video/document/audio).

download_media

Download media from a message.

ping

Health check tool.