whatsapp

This MCP server provides seven tools to manage and interact with your WhatsApp data through Claude and other LLMs: list_chats, list_messages, search_messages, send_message, download_media, get_connection_status, and catch_up. The server runs as a Docker container and persists its data to a mounted host directory to keep chat history and media across restarts. To use it, start the container with a volume mounted to /app/store and then query the available tools via Claude or any MCP-compatible interface. The tools let you list conversations with filtering and pagination, fetch and search message history with full-text search, send messages or media with fuzzy name matching and threading, download media to local storage, check connection and database statistics, and generate intelligent activity summaries of your WhatsApp activity. Ensure you configure environment variables such as DB_DIR and LOG_LEVEL if you need custom paths or logging detail.

Prerequisites:

• Docker installed on your machine
• Sufficient permissions to run containers

Installation steps:

1. Pull the latest image:

docker pull ghcr.io/eddmann/whatsapp-mcp:latest

2. Create a directory for persistent storage on your host:

mkdir -p whatsapp-store

3. Run the container with a mounted volume to persist data:

docker run -it --rm \
  -v "$(pwd)/whatsapp-store:/app/store" \
  ghcr.io/eddmann/whatsapp-mcp:latest

4. On first run, a QR code will appear in the terminal for pairing. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the QR code. Wait for the history sync to complete (look for logs indicating history sync persistence counts).

Optional with Claude Desktop integration:

• Use the provided Claude configuration snippet to add the WhatsApp MCP server, and adjust the volume path and environment variables as needed.

Notes:

• Session data is saved under store/whatsapp.db and messages under store/messages.db
• Media downloads go to store/<chatJID>/ directories
• If you need persistent storage, mount an absolute path to /app/store as shown above.

Tips and common issues:

• Always mount an absolute host path to /app/store to ensure persistence across container restarts.
• If you encounter login issues after a restart, ensure the store directory contains the expected WhatsApp session data; the server should automatically reconnect using stored credentials.
• Configure LOG_LEVEL for debugging (e.g., DEBUG) if you are troubleshooting.
• The available environment variables (DB_DIR, LOG_LEVEL, FFMPEG_PATH) can be customized in your orchestration tool or Claude config to suit your environment.
• For production, consider securing access to the container and restricting Claude's access to the MCP endpoints.