WhatsApp MCP Server

A Model Context Protocol (MCP) server for WhatsApp, enabling Claude to read and send WhatsApp messages.

Originally created by Luke Harries. Maintained by Very Good Plugins.

Watch the WhatsApp MCP demo video

Product demo generated with Remotion using simulated data.

Features

• Message Management: Search and read personal WhatsApp messages (text, images, videos, documents, audio)
• Contact Search: Search contacts by name or phone number with sender_display format ("Name (phone)")
• Send Messages: Send text messages to individuals or groups
• Read Receipts: Explicitly mark selected messages as read across linked devices
• Media Support: Send and download images, videos, documents, and voice messages
• Call History: Capture incoming voice/video calls into a local SQLite table (live, 1:1 and group)
• Webhook Integration: Forward incoming messages to external services
• Local Storage: All messages stored locally in SQLite - only sent to Claude when you allow it

Installation

Prerequisites

• Go 1.26+
• Python 3.11+
• uv package manager
• Claude Desktop or Cursor
• FFmpeg (optional, for voice message conversion)

Quick Start

1. Clone the repository

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

2. Start the WhatsApp bridge

   cd whatsapp-bridge
   go run .
   

   On first start, the bridge prints and stores a local REST API token at whatsapp-bridge/store/.bridge-token. Scan the QR code with WhatsApp on your phone to authenticate.

3. Configure Claude Desktop

   Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/whatsapp-mcp/whatsapp-mcp-server",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Replace /path/to/whatsapp-mcp with your actual path.

4. Restart Claude Desktop

Updating

Pull the latest changes, then refresh whichever components moved:

git pull

You changed	What to do
Bridge code (whatsapp-bridge/*.go) and you run go run .	Nothing — go run recompiles each launch. Just restart the bridge.
Bridge code and you run a built binary	cd whatsapp-bridge && go build -o whatsapp-bridge && ./whatsapp-bridge
MCP server (whatsapp-mcp-server/*.py, pyproject.toml, uv.lock)	Restart Claude Desktop / Cursor — uv re-resolves from the lockfile on next launch. Force a sync with cd whatsapp-mcp-server && uv sync if needed.