This project provides a Model Context Protocol (MCP) server that integrates WhatsApp with AI models like Claude, enabling users to search messages, manage contacts, and send messages/media directly from their AI interface. It targets AI power users and developers seeking to leverage conversational AI for personal communication management.

How It Works

The system comprises a Go-based WhatsApp bridge and a Python MCP server. The Go bridge connects to WhatsApp's web API via the whatsmeow library, handling authentication (QR code scanning) and storing message history in a local SQLite database. The Python MCP server exposes tools for AI models to query this database and interact with WhatsApp through the Go bridge, facilitating message retrieval, contact searching, and sending messages or media.

Quick Start & Requirements

• Install Python 3.6+ and uv (Python package manager).
• Install FFmpeg for automatic audio conversion to .ogg Opus format for voice messages.
• Clone the repository: git clone https://github.com/lharries/whatsapp-mcp.git
• Run the Go WhatsApp bridge: cd whatsapp-bridge && go run main.go (scan QR code for authentication).
• Configure the MCP server path in claude_desktop_config.json or mcp.json for Claude or Cursor respectively.
• Restart Claude Desktop or Cursor to enable the WhatsApp integration.
• Windows users must enable CGO_ENABLED=1 and install a C compiler (e.g., via MSYS2).

Highlighted Details

• Supports searching and reading messages, including media (images, videos, documents, audio).
• Enables sending messages to individuals or groups and sending various media types.
• Stores all message history locally in a SQLite database.
• Provides tools for AI models to interact with WhatsApp data, such as search_contacts, list_messages, send_message, and send_file.
• Automatically converts non-Opus audio files to .ogg Opus format using FFmpeg for voice messages.

Maintenance & Community

• Project maintained by lharries.
• Links to email signup for updates are provided.
• Further integration troubleshooting details are available in the MCP documentation.

Licensing & Compatibility

• The README does not explicitly state a license.

Limitations & Caveats

WhatsApp's multi-device API requires re-authentication approximately every 20 days. Users may encounter device limits imposed by WhatsApp. Initial message history loading can take several minutes. Sync issues may require re-authentication and database resets.