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.
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)
Intel macOS: patched cryptography releases no longer provide Intel Mac
wheels, so installation may compile this dependency from source. Install the
Xcode Command Line Tools (xcode-select --install) and, with Homebrew,
brew install rust openssl@3 pkg-config. Then install the Python dependencies:
cd whatsapp-mcp-server
OPENSSL_DIR="$(brew --prefix openssl@3)" uv sync
Use a Rust toolchain supported by the installed cryptography release; see its
source-build instructions.
Keep the patched dependency rather than restoring the old vulnerable version pin.
Quick Start
-
Clone the repository
git clone https://github.com/verygoodplugins/whatsapp-mcp.git
cd whatsapp-mcp
-
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.
-
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.
-
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. |
Updates do not require re-pairing or deleting whatsapp.db — your session and message history are preserved. Re-pairing is only needed when explicitly requesting full history (see Requesting full history).
For v0.2.1 and later, restart both the bridge and MCP server after updating
so the MCP server can read the bridge token. If the two components do not share
the same checkout, set the same WHATSAPP_BRIDGE_TOKEN value in both
environments.
Cursor IDE Configuration
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"
]
}
}
}
}
Tools
Messages include sender_display showing "Name (phone)" format for easy identification by agents.
Contact Operations
search_contacts
Search contacts by name or phone number.
Parameters:
query (required): Name or phone number to search
Natural Language Examples:
- "Find contacts named John"
- "Search for phone number 555-1234"
- "Who has the phone number starting with +1?"
get_contact
Resolve a WhatsApp contact name from a phone number, LID, or full JID.
Parameters:
identifier (required): Phone number, LID, or full JID (aliases: phone_number, phone)
Natural Language Examples:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
