The WhatsApp MCP Server enables Claude to read and send WhatsApp messages by exposing a structured MCP interface backed by a Python-based MCP server. It supports searching and reading messages (including media), locating contacts, sending text messages, handling media (images, videos, documents, voice), and webhook forwarding of incoming messages. The server is designed to integrate with Claude Desktop or Cursor via MCP, providing a set of tools grouped under Contact, Message, Chat, and Media operations that Claude can invoke through natural language prompts or scripted workflows. The bridge components store messages locally in SQLite and expose a REST API that the MCP layer uses to perform actions through WhatsApp connections managed by the bridge.

Prerequisites:

• Go 1.24+ and Python 3.11+ (for the bridge and MCP server)
• uv package manager (for Python MCP integration)
• Claude Desktop or Cursor IDE
• FFmpeg (optional, for voice message conversion)

Quick-start installation:

1. Clone the repository: git clone https://github.com/verygoodplugins/whatsapp-mcp.git cd whatsapp-mcp

2. Start the WhatsApp bridge (Go-based bridge): cd whatsapp-bridge go run main.go

   Scan the QR code with WhatsApp on your phone to authenticate

3. Configure Claude Desktop to load the MCP server: Add to Claude Desktop configuration (example path shown): { "mcpServers": { "whatsapp": { "command": "uv", "args": [ "--directory", "/path/to/whatsapp-mcp/whatsapp-mcp-server", "run", "main.py" ] } } }

4. Restart Claude Desktop to pick up the new MCP server.

Optional Cursor IDE setup: Add to your Cursor MCP settings (~/.cursor/mcp.json): { "mcp": { "servers": { "whatsapp": { "command": "uv", "args": [ "--directory", "/path/to/whatsapp-mcp/whatsapp-mcp-server", "run", "main.py" ] } } } }

Environment and configuration tips:

• The MCP server runs Python code via uv; ensure the path in --directory points to the whatsapp-mcp-server directory containing main.py.
• The bridge stores messages locally in SQLite (WHATSAPP_DB_PATH). Ensure the path is writable.
• Webhook integration is supported; configure WEBHOOK_URL to point to your receiver. The WHATSAPP_BRIDGE_PORT controls the REST API exposed by the Go bridge.
• If you’re using voice messages, FFmpeg should be installed to enable conversion to Opus format.
• For production, consider securing your endpoints and rotating credentials, especially if you enable webhooks or expose the REST API publicly.
• The tools scheme includes Contact Tools (search_contacts, get_contact), Message Tools (list_messages, send_message, send_file, send_audio_message, download_media), and Chat Tools (list_chats, get_chat, get_direct_chat_by_contact, get_contact_chats, get_last_interaction, get_message_context).
• Logs can be found in the MCP server output and the bridge logs; monitor for authentication QR scans and message flow.