WhatsApp MCP Server

This is a Model Context Protocol (MCP) server for WhatsApp.

With this you can search and read your personal Whatsapp messages (including images, videos, documents, and audio messages), search your contacts and send messages to either individuals or groups. You can also send media files including images, videos, documents, and audio messages.

It connects to your personal WhatsApp account directly via the Whatsapp web multidevice API (using the whatsmeow library). All your messages are stored locally in a SQLite database and only sent to an LLM (such as Claude) when the agent accesses them through tools (which you control).

Here's an example of what you can do when it's connected to Claude.

To get updates on this and other projects I work on enter your email here

Caution: as with many MCP servers, the WhatsApp MCP is subject to the lethal trifecta. This means that project injection could lead to private data exfiltration.

Installation

Prerequisites

Go
Python 3.10+
Anthropic Claude Desktop app (or Cursor) for stdio mode, or any MCP client for HTTP mode
UV (Python package manager), install with curl -LsSf https://astral.sh/uv/install.sh | sh
FFmpeg (optional) - Only needed for audio messages. If you want to send audio files as playable WhatsApp voice messages, they must be in .ogg Opus format. With FFmpeg installed, the MCP server will automatically convert non-Opus audio files. Without FFmpeg, you can still send raw audio files using the send_file tool.
MySQL (optional) - By default, the system uses SQLite. For better performance with large message histories, you can configure MySQL instead.

Steps

Clone this repository

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

Configure the WhatsApp bridge (optional)

The WhatsApp bridge can be configured via environment variables in whatsapp-bridge/.env. Create this file if it doesn't exist:

cd whatsapp-bridge
cp .env.example .env  # If example exists, or create new file

Key configuration options:

# Device name that appears in WhatsApp > Linked Devices
DEVICE_NAME=WhatsApp MCP Server

# Database engine: 'sqlite' (default) or 'mysql'
DB_ENGINE=sqlite

# MySQL settings (only if DB_ENGINE=mysql)
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=your_password
DB_NAME=whatsapp_bridge

# REST API port for the Go bridge
API_PORT=9095

# MCP Server mode: 'stdio' (default for Claude Desktop) or 'streamable' (for HTTP access)
MCP_MODE=stdio

# MCP Server HTTP settings (only if MCP_MODE=streamable)
MCP_HOST=0.0.0.0
MCP_PORT=9096

Database Setup:

SQLite (default): No additional setup required. Database files are created automatically in whatsapp-bridge/store/.
MySQL: Create the database and tables using the provided SQL schema:
```
mysql -u root -p < whatsapp-bridge/etc/mysql.sql
```

Run the WhatsApp bridge

Navigate to the whatsapp-bridge directory and run the Go application:
```
cd whatsapp-bridge
go run main.go
```
The first time you run it, you will be prompted to scan a QR code. Scan the QR code with your WhatsApp mobile app to authenticate.

After approximately 20 days, you will might need to re-authenticate.
Connect to the MCP server

The MCP server supports two modes of operation:

Stdio Mode (Default - for Claude Desktop/Cursor)

Copy the below json with the appropriate {{PATH}} values:
```
{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}
```
For Claude, save this as claude_desktop_config.json in your Claude Desktop configuration directory at:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
For Cursor, save this as mcp.json in your Cursor configuration directory at:
```
~/.cursor/mcp.json
```
Or restart Cursor.

Streamable HTTP Mode (for custom integrations)

To run the MCP server as an HTTP endpoint accessible from any MCP client:
1. Set MCP_MODE=streamable in whatsapp-bridge/.env
2. Optionally configure MCP_HOST and MCP_PORT (defaults: 0.0.0.0:9096)
3. Start both the WhatsApp bridge and MCP server:
```
# Terminal 1: Start WhatsApp bridge
cd whatsapp-bridge
go run main.go

# Terminal 2: Start MCP server in HTTP mode
cd whatsapp-mcp-server
uv run main.py
```
4. The MCP server will be available at http://localhost:9096 (or your configured host/port)
5. Connect your MCP client to this HTTP endpoint
Restart Claude Desktop / Cursor

Open Claude Desktop and you should now see WhatsApp as an available integration.

Or restart Cursor.

Windows Compatibility

If you're running this project on Windows, be aware that go-sqlite3 requires CGO to be enabled in order to compile and work properly. By default, CGO is disabled on Windows, so you need to explicitly enable it and have a C compiler installed.

Steps to get it working:

Install a C compiler
We recommend using MSYS2 to install a C compiler for Windows. After installing MSYS2, make sure to add the ucrt64\bin folder to your PATH.
→ A step-by-step guide is available here.

Enable CGO and run the app

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

Without this setup, you'll likely run into errors like:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Architecture Overview

This application consists of three main components:

Go WhatsApp Bridge (whatsapp-bridge/): A Go application that connects to WhatsApp's web API, handles authentication via QR code, and stores message history. It serves as the bridge between WhatsApp and the MCP server and provides a REST API for message operations.
Python MCP Server (whatsapp-mcp-server/): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude (or other MCP clients) to interact with WhatsApp data and send/receive messages. Supports both stdio mode (for Claude Desktop/Cursor) and HTTP mode (for custom integrations).
WhatsApp Agent (whatsapp-agent/): An autonomous agent that monitors incoming WhatsApp messages and automatically responds using GPT-4 with access to MCP tools. The agent can search the web (via Tavily), access conversation history, send messages to contacts, and handle multi-step tasks.

Data Storage

Message history can be stored in either SQLite (default) or MySQL (configured via .env)
SQLite: Database files stored in whatsapp-bridge/store/ directory
MySQL: Centralized database for better performance with large message histories
The database maintains tables for chats (di_chats) and messages (ft_messages)
Messages are indexed for efficient searching and retrieval

Usage

Once connected, you can interact with your WhatsApp contacts through Claude, leveraging Claude's AI capabilities in your WhatsApp conversations.

MCP Tools

Claude can access the following tools to interact with WhatsApp:

search_contacts: Search for contacts by name or phone number
list_messages: Retrieve messages with optional filters and context
list_chats: List available chats with metadata
get_chat: Get information about a specific chat
get_direct_chat_by_contact: Find a direct chat with a specific contact
get_contact_chats: List all chats involving a specific contact
get_last_interaction: Get the most recent message with a contact
get_message_context: Retrieve context around a specific message
send_message: Send a WhatsApp message to a specified phone number or group JID
send_file: Send a file (image, video, raw audio, document) to a specified recipient
send_audio_message: Send an audio file as a WhatsApp voice message (requires the file to be an .ogg opus file or ffmpeg must be installed)
download_media: Download media from a WhatsApp message and get the local file path or base64-encoded content

Media Handling Features

The MCP server supports both sending and receiving various media types:

Media Sending

You can send various media types to your WhatsApp contacts:

Images, Videos, Documents: Use the send_file tool to share any supported media type.
Voice Messages: Use the send_audio_message tool to send audio files as playable WhatsApp voice messages.
- For optimal compatibility, audio files should be in .ogg Opus format.
- With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to the required format.
- Without FFmpeg, you can still send raw audio files using the send_file tool, but they won't appear as playable voice messages.

Media Downloading

By default, just the metadata of the media is stored in the local database. The message will indicate that media was sent. To access this media you need to use the download_media tool:

Parameters:
- message_id: The ID of the message (shown when listing messages with media)
- chat_jid: Optional - The chat JID (auto-detected if not provided)
- return_base64: Optional boolean (default: false)
  - false: Returns the local file path where media was downloaded
  - true: Returns the media content as a base64-encoded string (useful for direct API integration or embedding in responses)

Usage examples:

# Get file path
download_media(message_id="ABC123...")
# Returns: {"success": true, "file_path": "/path/to/file.jpg"}

# Get base64 content
download_media(message_id="ABC123...", return_base64=true)
# Returns: {"success": true, "base64_content": "iVBORw0KGgo..."}

Note: WhatsApp media files expire after approximately 30 days. Only recent media can be downloaded from WhatsApp's servers.

WhatsApp Agent

The WhatsApp Agent is an autonomous assistant that monitors your incoming WhatsApp messages and automatically responds using GPT-4 with access to all MCP tools.

Features

Autonomous Message Processing: Continuously monitors for new incoming messages and generates intelligent responses
Image Analysis: Automatically detects and processes images sent to WhatsApp, providing detailed descriptions, answering questions about images, or extracting information from them (powered by GPT-4o Vision)
Multi-Tool Access: Can use all WhatsApp MCP tools (search contacts, send messages, get conversation context, etc.)
Web Search Integration: Integrated with Tavily for real-time web searches to answer questions with current information
Browser Automation: Optional Playwright integration for advanced web scraping, screenshots, and interactive browser tasks
Multi-Language Support: Automatically detects and responds in the language of the conversation
Contact Message Forwarding: Can send messages to other contacts in your address book on your behalf
Conversation Context: Maintains context from previous messages (up to 100 messages) for coherent conversations

Configuration

Configure the agent in your root .env file:

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key

# Tavily Search (optional but recommended for web searches)
TAVILY=yes  # Set to 'yes' to enable web search capabilities
TAVILY_CMD=@modelcontextprotocol/server-tavily
TAVILY_API_KEY=tvly-your-tavily-api-key  # Get free key at tavily.com

# Playwright (optional - for browser automation and web scraping)
PLAYWRIGHT=yes  # Set to 'yes' to enable browser automation
PLAYWRIGHT_CMD=@executeautomation/playwright-mcp-server

# MCP Mode (should match your MCP server configuration)
MCP_MODE=streamable  # or 'stdio'
MCP_HOST=0.0.0.0
MCP_PORT=9096

Running the Agent

Make sure both the WhatsApp bridge and MCP server are running, then start the agent:

# Activate the virtual environment
source venv/bin/activate

# Run the agent
python whatsapp-agent/agent.py

The agent will:

Connect to the MCP server (WhatsApp and optionally Tavily)
Start monitoring for new incoming messages
Process each message with GPT-4
Generate and send responses automatically

Agent Capabilities

The agent is designed to:

Answer questions using conversation context and web search when needed
Analyze images: When you send an image, the agent can describe what it sees, answer questions about the image, extract text, identify objects, and more
Send messages to contacts: When you say "Tell Juan that..." or "Send Maria...", it will:
1. Search for the contact by name
2. Send them the message you specified
3. Confirm back to you what was sent
Provide current information: Automatically searches the web for news, weather, stock prices, etc.
Maintain natural conversations: Adapts language and tone based on context
Handle media: Can work with images, videos, and audio messages (through MCP tools)

Example Interactions

You: "What's the weather like in Madrid today?"
Agent: [Searches web via Tavily] "Today in Madrid it's partly cloudy with temperatures..."

You: [Sends an image of a receipt]
Agent: [Analyzes image with GPT-4o Vision] "I can see a receipt from Mercadona for 45.67€. The items include..."

You: [Sends a photo] "What do you see in this image?"
Agent: [Analyzes image] "This appears to be a photo of... with... in the background..."

You: "Tell Juan we're meeting at 5pm tomorrow"
Agent: [Searches contact "Juan", sends message] "I've sent Juan: 'We're meeting at 5pm tomorrow'"

You: "What did Maria say yesterday?"
Agent: [Retrieves conversation context] "Yesterday Maria said..."

Important Notes

The agent processes messages automatically - it will respond to all incoming messages
Messages are marked as processed to avoid duplicate responses
The agent requires an OpenAI API key and uses:
- GPT-4 Turbo for text-only messages
- GPT-4o for messages containing images (enabling vision capabilities)
Tavily integration is optional but recommended for current information queries
The agent respects conversation context and language preferences
Image processing requires the message to be recent (WhatsApp media expires after ~30 days)

Technical Details

Claude sends requests to the Python MCP server
The MCP server queries the Go bridge for WhatsApp data or directly to the database
The Go bridge accesses the WhatsApp API and keeps the database up to date
Data flows back through the chain to Claude
When sending messages, the request flows from Claude through the MCP server to the Go bridge and to WhatsApp
The WhatsApp Agent operates independently, monitoring the database for new messages and using the MCP server to process and respond

Troubleshooting

If you encounter permission issues when running uv, you may need to add it to your PATH or use the full path to the executable.
Make sure both the Go application and the Python server are running for the integration to work properly.

Authentication Issues

QR Code Not Displaying: If the QR code doesn't appear, try restarting the authentication script. If issues persist, check if your terminal supports displaying QR codes.
WhatsApp Already Logged In: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.
Device Limit Reached: WhatsApp limits the number of linked devices. If you reach this limit, you'll need to remove an existing device from WhatsApp on your phone (Settings > Linked Devices).
No Messages Loading: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.
WhatsApp Out of Sync: If your WhatsApp messages get out of sync with the bridge, delete both database files (whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db) and restart the bridge to re-authenticate.

For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.

MCP Servers