whatsapp

This MCP server provides a Python-based MCP that interfaces with a connected WhatsApp account via a Go bridge. It exposes a set of tools Claude or similar agents can invoke to search contacts, read messages, manage chats, and send media or messages through WhatsApp. The server enables reading message history stored locally in SQLite and performing actions such as sending messages or files to individuals or groups, as well as downloading media from messages. To use it, first ensure your WhatsApp bridge is running and the MCP server is active behind the UV-managed Python process so Claude (or Cursor) can call its tools to interact with WhatsApp data.

Key capabilities include the following 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, and download_media. These tools enable you to locate a contact, fetch conversation history with optional filters, inspect chat metadata, and perform messaging operations, including sending media such as images, videos, documents, and audio. Media handling supports both sending and retrieving media; audio messages can be played back when encoded as .ogg Opus and FFmpeg can be used to convert other formats if installed.

Operational flow: Claude sends requests to the Python MCP server, which queries the Go WhatsApp bridge or the local SQLite database as needed, and then returns results to Claude. When sending messages, requests flow from Claude through the MCP server to the bridge and ultimately to WhatsApp. This setup allows you to leverage an LLM-driven assistant to manage WhatsApp communications while keeping your message history locally stored and access-controlled.

Prerequisites

• Go (for the WhatsApp bridge)
• Python 3.6+ (for the MCP server)
• UV (Python package manager) to run the Python MCP server: install with the command below
• Anthropic Claude Desktop app (or Cursor) to connect to the MCP server
• FFmpeg (optional) if you plan to send playable voice messages; required for automatic audio format conversion

Installation steps

1. Install UV (Python package manager)

   • Run the installer script provided in the README: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install prerequisites on your system (example commands)

   • Ensure Go is installed for the WhatsApp bridge (Go is required to run the bridge)
   • Ensure Python 3.6+ is installed for the MCP server
   • Optionally install FFmpeg if you want automatic audio conversion for voice messages

3. Clone the repository and set up

   • git clone https://github.com/lharries/whatsapp-mcp.git
   • cd whatsapp-mcp

4. Run the WhatsApp bridge (Go application)

   • Navigate to the bridge directory and start it: cd whatsapp-bridge go run main.go
   • First-time authentication requires scanning a QR code with WhatsApp; re-authentication may be required after some time

5. Run the MCP server (Python) via UV

   • Ensure you are in the project root and start the MCP server with UV using the following command structure (adjust paths as needed): uvx --directory {{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server run main.py

6. Connect tools to Claude or Cursor

   • Claude: save the generated JSON configuration as claude_desktop_config.json in your Claude Desktop config directory
   • Cursor: save the configuration as mcp.json in your Cursor config directory

7. Restart the client

   • Restart Claude Desktop or Cursor to enable the WhatsApp integration

Notes for Windows users

• Windows may require CGO settings for the Go-based bridge; see Windows compatibility notes in the repository for enabling CGO if needed.

Tips and common issues:

• Ensure the WhatsApp bridge is running and authenticated before starting the MCP server; the MCP relies on the bridge for data access
• The SQLite database stores message history locally; regular backups are recommended if you rely on this data
• If you encounter path or PATH issues with UV, provide the full path to the UV executable in your environment or use the absolute path in the command
• For voice messages, FFmpeg simplifies conversion to playable .ogg Opus format; without FFmpeg you can still send raw audio files via send_file, but they won't be playable as voice messages
• Be mindful of privacy and security considerations when connecting your personal WhatsApp account to an MCP server; avoid exposing credentials or access tokens in logs or configuration files
• If you experience QR authentication problems, restarting the authentication script or reauthenticating may help; ensure you are scanning with the correct WhatsApp account
• The MCP server may be subject to external data access considerations; follow best practices to minimize data exposure and securely manage local data storage