whatsapp-mcp by eddmann - MCP Server

WhatsApp MCP Server

A Model Context Protocol (MCP) server for WhatsApp integration. Send messages, search conversations, and access your WhatsApp history through Claude and other LLMs.

Overview

This MCP server provides 7 tools to interact with your WhatsApp account via the whatsmeow library:

list_chats - List conversations with filtering, sorting, and pagination
list_messages - Retrieve message history with date range filtering and context
search_messages - Full-text search across all messages using SQLite FTS5 with context
send_message - Send text and media messages with fuzzy name matching and reply/threading
download_media - Download media files from conversations to local storage
get_connection_status - Check WhatsApp connection status and database statistics
catch_up - Intelligent activity summary showing recent chats, questions, and media

All messages and chats are persisted to a local SQLite database with full-text search capabilities, enabling rich queries and analysis of your WhatsApp history.

Prerequisites

Docker

Installation & Setup

# Pull the image
docker pull ghcr.io/eddmann/whatsapp-mcp:latest

First Run - WhatsApp Pairing

# Create directory for persistent storage
mkdir -p whatsapp-store

# Run the container (QR code will be displayed)
docker run -it --rm \
  -v "$(pwd)/whatsapp-store:/app/store" \
  ghcr.io/eddmann/whatsapp-mcp:latest

On first run, a QR code will be displayed in the terminal:

Open WhatsApp on your phone
Go to Settings → Linked Devices → Link a Device
Scan the QR code displayed in your terminal
Wait for history sync to complete (check logs for "history sync persisted messages count=...")

Authentication & Data Storage

Session Storage: WhatsApp session data is saved to store/whatsapp.db and persists across restarts
Message Database: All messages and chats are stored in store/messages.db with FTS5 full-text search
Media Downloads: Downloaded media files are organized in store/<chatJID>/ directories
No Re-Authentication: After initial pairing, the server automatically reconnects using stored credentials

Important: Mount a volume to /app/store to persist session data and messages across container restarts.

Claude Desktop Configuration

Add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Basic Configuration

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/whatsapp-store:/app/store",
        "ghcr.io/eddmann/whatsapp-mcp:latest"
      ]
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/whatsapp-store:/app/store",
        "-e",
        "LOG_LEVEL=DEBUG",
        "ghcr.io/eddmann/whatsapp-mcp:latest"
      ]
    }
  }
}

Available Environment Variables

DB_DIR - Directory for SQLite databases and downloaded media - default: store
LOG_LEVEL - Logging level (DEBUG, INFO, WARN, ERROR) - default: INFO
FFMPEG_PATH - Path to ffmpeg binary for audio conversion - default: ffmpeg

Usage

Ask Claude to interact with your WhatsApp data using natural language.

Sending Messages

"Send a message to John saying I'll be there in 10 minutes"
"Send a photo from ~/Desktop/photo.jpg to Bob"
"Send this audio recording to the Project Team group"
"Reply to that message from Sarah saying 'Sounds good!'"

Recipient Formats (with fuzzy name matching):

Contact/group names: "John", "Bob", "Project Team" (searches your chat history)

Phone numbers: Without + (e.g., 447123456789)

Full JID: 447123456789@s.whatsapp.net for contacts, 123456@g.us for groups

If multiple matches are found for a name, you'll be prompted to disambiguate using the full JID.

Message Threading:

Reply to specific messages to create threaded conversations. The original message will be quoted in your reply.

Viewing Conversations

"Show me my recent chats"
"List my last 20 messages with John"
"Show the conversation with Dad from yesterday with context"

Searching Messages

"Search for all messages mentioning 'project deadline'"
"Find messages from Alice about the meeting"
"Search for 'birthday party' in my group chats"

Media Handling

"Download the latest photo from the Family group"
"Save that video Mick sent me yesterday"

Getting Activity Summaries

"Catch me up on today's WhatsApp activity"
"Show me what happened in my WhatsApp groups this week"
"What questions have I been asked today?"

Available Tools

Tool	Description
`list_chats`	List conversations with message previews, sorted by recent activity. Filter by name/phone/groups-only. Supports pagination.
`list_messages`	List messages from a conversation. Filter by contact/group name and date range using natural timeframes (today, this_week, etc).
`search_messages`	Full-text search with FTS5 across all messages. Supports keywords, phrases, boolean operators, and date filters.
`send_message`	Send text, media (image/video/audio/document), or both to contacts/groups. Fuzzy name matching and message reply/threading support.
`download_media`	Download media files (image/video/audio/document) from messages to local storage organized by chat.
`get_connection_status`	Check WhatsApp connection status, login state, device info, and database statistics (chat and message counts).
`catch_up`	Intelligent activity summary showing active chats with recent messages, questions directed at you, media activity, and attention flags.

License

MIT License - see file for details

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by WhatsApp Inc. or Meta Platforms, Inc. Use at your own risk. Ensure compliance with WhatsApp's Terms of Service when using this software.

Credits

Inspired by lharries/whatsapp-mcp