whatsapp-mcp

WhatsApp MCP Server is a Model Context Protocol (MCP)-based server used to connect a personal WhatsApp account with AI agents (such as Claude). Through this server, AI can search and read personal WhatsApp messages (including images, videos, documents, and audio messages), search contacts, and send messages to individuals or groups, and can also send media files. It connects directly to a personal WhatsApp account through the WhatsApp Web multi-device API (using the whatsmeow library). All messages are stored locally in a SQLite database and are only sent to the LLM (such as Claude) when the agent accesses them through tools.

Purpose: To provide AI assistants with the ability to access and operate a personal WhatsApp account, enabling message queries, contact management, and message sending.

Main capabilities:

• Search contacts (by name or phone number).
• Retrieve messages (with filtering and context support).
• List chats, get chat information, find direct chats by contact, list all chats involving a contact, get recent interactions, get message context.
• Send messages to a specified phone number or group JID.
• Send files (images, videos, raw audio, documents).
• Send audio messages as WhatsApp voice messages (.ogg Opus format required, or install FFmpeg for automatic conversion).
• Download media files in messages and get local paths.
• Support receiving various media types; by default only metadata is stored, and media must be downloaded using the download_media tool.

Usage:

1. Prerequisites: Anthropic Claude Desktop application (or Cursor), UV (Python package manager, installation command: curl -LsSf https://astral.sh/uv/install.sh | sh), FFmpeg (optional, only needed for audio messages).
2. Clone the repository: git clone https://github.com/lharries/whatsapp-mcp.git then cd whatsapp-mcp.
3. Run the WhatsApp bridge: enter the whatsapp-bridge directory and run the Go application: cd whatsapp-bridge then go run main.go. On first run, it will prompt you to scan a QR code; scan it with the WhatsApp mobile app to authenticate. Re-authentication may be required after about 20 days.
4. Connect the MCP server: copy the provided JSON configuration and replace the {{PATH}} value. For Claude, save it as claude_desktop_config.json to ~/Library/Application Support/Claude/claude_desktop_config.json; for Cursor, save it as mcp.json to ~/.cursor/mcp.json.
5. Restart Claude Desktop or Cursor, and you will see the WhatsApp integration.

Windows compatibility: go-sqlite3 requires CGO to be enabled and a C compiler to be installed. It is recommended to use MSYS2 to install a C compiler and add ucrt64\bin to PATH. Then enable CGO and run: cd whatsapp-bridge, go env -w CGO_ENABLED=1, go run main.go. Otherwise, you may encounter the error: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Architecture overview:

• Go WhatsApp bridge (whatsapp-bridge/): connects to the WhatsApp Web API, handles QR code authentication, and stores message history in SQLite.
• Python MCP server (whatsapp-mcp-server/): implements MCP and provides standardized tools for Claude to interact with. Message history is stored in a SQLite database under whatsapp-bridge/store/, containing chats and messages tables, with messages indexed for efficient search.

Available tools: search_contacts, list_messages, list_chats, get_chat, get_direct_chat_by_contact, get_contact_chats, get_last_interaction, get_message_context, send_message, send_file, send_audio_message, download_media.

Media handling: can send images, videos, documents (send_file), voice messages (send_audio_message, .ogg Opus format recommended, installing FFmpeg enables automatic conversion of other formats). By default only media metadata is stored; you need to use download_media to download and obtain the local path.

Technical details: Claude sends requests to the Python MCP server, the MCP server queries the Go bridge or directly queries SQLite, Go accesses the WhatsApp API and keeps the database updated. When sending messages, requests flow through the MCP server and the Go bridge to WhatsApp.

Troubleshooting:

• uv permission issues: add to PATH or use the full path.
• Make sure both the Go application and the Python server are running.
• QR code not displaying: restart the authentication script, check whether the terminal supports displaying QR codes.
• Already logged in: the Go bridge reconnects automatically and does not display a QR code.
• Device limit: you need to remove an existing device in WhatsApp on your phone (Settings > Linked Devices).
• Messages not loading: it may take a few minutes to load history after initial authentication.
• Not syncing: delete whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db, restart the bridge and re-authenticate.

Limitations and notes:

• Like many MCP servers, WhatsApp MCP is affected by the "lethal trifecta", and project injection may lead to leakage of private data.
• All messages are stored locally and are only sent to the LLM when the agent accesses them through tools.
• Audio messages require .ogg Opus format or installing FFmpeg for conversion.
• Windows requires additional configuration of CGO and a C compiler.
• Re-authentication may be required after about 20 days.
• WhatsApp has a limit on the number of linked devices.