MCP server/communication

WhatsApp MCP Stream MCP Server

WhatsApp MCP server with Streamable HTTP transport and web admin UI

★ 5loglux/whatsapp-mcp-stream ↗by logluxupdated
1

Add it to Claude Code

claude mcp add whatsapp-mcp-stream -- docker run -i --rm -p 3003:3003 loglux/whatsapp-mcp-stream
2

Make your agent remember this setup

whatsapp-mcp-stream's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session. 

npx conare@latest

Free · one command · indexes the sessions already on disk. Set up in the browser instead →

What it does

  • Bidirectional media flow with upload and download capabilities
  • Web-based admin UI for QR code authentication and runtime settings
  • Comprehensive tools for managing contacts, chats, and group metadata
  • Advanced group auditing tools to find overlaps and missing contacts
  • Support for idempotency keys in message and media sending

Tools 26

get_qr_codeGet the latest WhatsApp QR code as an image for authentication.
check_auth_statusCheck if the WhatsApp client is authenticated and ready.
logoutLogout from WhatsApp and clear the current session.
search_contactsSearch contacts by name or phone number.
resolve_contactResolve a contact by name or phone number.
get_contact_by_idGet contact details by JID.
get_profile_picGet profile picture URL for a JID.
get_group_infoGet group metadata and participants by group JID.
list_chatsList chats with metadata and optional last message.
get_chat_by_idGet chat metadata by JID.
list_groupsList group chats only.
get_direct_chat_by_contact_numberResolve a direct chat JID by phone number.
get_chat_by_contactResolve a contact by name or phone number and return chat metadata.
analyze_group_overlapsFind members that appear across multiple groups.
find_members_without_direct_chatFind group members with no direct chat.
find_members_not_in_contactsFind group members missing from contacts.
run_group_auditRun combined group audit as one routine operation.
list_messagesGet messages from a specific chat.
search_messagesSearch messages by text.
get_message_by_idGet a specific message by ID.
get_message_contextGet recent messages around a specific message.
get_last_interactionGet the most recent message for a JID.
send_messageSend a text message to a person or group.
send_mediaSend media (image/video/document/audio).
download_mediaDownload media from a message.
pingHealth check tool.

Environment Variables

MEDIA_DIRDirectory for storing media files
SETTINGS_PATHPath to the settings JSON file
MCP_BASE_URLBase URL for the MCP endpoint

Try it

→Check if my WhatsApp client is currently authenticated and ready.
→Search for my contact 'John Doe' and get his profile picture URL.
→List all my group chats and identify members who are not in my contacts.
→Send a message to the group 'Project Team' saying the report is ready.
→Download the latest image sent in the chat with 'Sarah'.
Original README from loglux/whatsapp-mcp-stream

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).

Admin UI

Admin UI Admin console with runtime settings, QR linking, 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:

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

Note: clients must send Accept: application/json, text/event-stream on initialize.

Smoke Test

Quick regression smoke for MCP tools:

npm run smoke:mcp

Optional custom target:

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

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.
run_group_audit Run combined group audit as one routine operation.

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. Supports optional idempotency_key.

Media

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

Utility

Tool Description
ping Health check tool.

Recovery Notes

This service contains an intentional recovery workaround for Baileys/WhatsApp session-state corruption.

Why it exists:

  • In production we observed cases where the container stayed alive and MCP still answered, but the WhatsApp session was functionally broken.

Frequently Asked Questions

What are the key features of WhatsApp MCP Stream?

Bidirectional media flow with upload and download capabilities. Web-based admin UI for QR code authentication and runtime settings. Comprehensive tools for managing contacts, chats, and group metadata. Advanced group auditing tools to find overlaps and missing contacts. Support for idempotency keys in message and media sending.

What can I use WhatsApp MCP Stream for?

Automating routine group management tasks like auditing member lists. Integrating WhatsApp messaging directly into AI-driven workflows. Managing media assets within WhatsApp chats via an MCP-compatible interface. Building custom dashboards for WhatsApp session monitoring and status.

How do I install WhatsApp MCP Stream?

Install WhatsApp MCP Stream by running: docker compose build && docker compose up -d

What MCP clients work with WhatsApp MCP Stream?

WhatsApp MCP Stream works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Conare · memory for coding agents

Turn this server into reusable context

Keep WhatsApp MCP Stream docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Set up free$npx conare@latest

Related MCP Servers

Vexa
Self-hosted meeting intelligence platform
communication2.7K stars
Claude Peers
Let your Claude Code instances find each other and talk.
communication2.2K stars
Wenyan MCP Server
Bridge AI writing and WeChat Official Account publishing with Markdown.
communication1.3K stars
KeyID Agent Kit
Give Claude, Cursor, or any MCP client a real email address. Free.
communication664 stars
Instagram MCP Server
Integrate with Instagram's Graph API for AI-driven account management.
communication177 stars
WeChat MCP Server
A WeChat robot server that enables AI agents to send and receive messages.
communication108 stars