WhatsApp MCP Server

What is WhatsApp MCP Server?

WhatsApp MCP Server is a Model Context Protocol (MCP) server designed to integrate your personal WhatsApp account with AI models such as Claude. It enables you to programmatically interact with your WhatsApp messages, contacts, and groups, facilitating advanced AI-driven communication and data analysis within your WhatsApp environment.

How to use WhatsApp MCP Server?

To use WhatsApp MCP Server, you need to follow these steps:

Prerequisites: Ensure you have Go, Python 3.6+, Anthropic Claude Desktop app (or Cursor), UV (Python package manager), and optionally FFmpeg installed.
Clone the repository: git clone https://github.com/lharries/whatsapp-mcp.git and navigate into the directory.
Run the WhatsApp bridge: Go to whatsapp-bridge directory and run go run main.go. The first time, you'll scan a QR code to authenticate your WhatsApp account.
Connect to the MCP server: Configure your Claude Desktop or Cursor application by adding a JSON configuration pointing to the whatsapp-mcp-server/main.py script. This involves specifying the path to uv and the whatsapp-mcp-server directory.
Restart Claude Desktop / Cursor: After configuration, restart your AI application to see WhatsApp as an available integration.

For Windows users, special attention is needed for go-sqlite3 which requires CGO to be enabled and a C compiler installed (e.g., via MSYS2).

Key Features of WhatsApp MCP Server

Personal WhatsApp Integration: Connects directly to your personal WhatsApp account using the WhatsApp web multi-device API.
Local Data Storage: All messages are stored locally in a SQLite database, ensuring privacy and control over your data.
AI Model Interaction: Designed to work seamlessly with LLMs like Claude, allowing AI agents to access and process WhatsApp data through defined tools.
Comprehensive Message Handling: Search, read, and send text messages, images, videos, documents, and audio messages.
Contact and Group Management: Search contacts, list chats, and send messages to individuals or groups.
Media Handling: Supports sending various media types (images, videos, documents, voice messages) and downloading media from messages. Automatic audio conversion to .ogg Opus format with FFmpeg.
MCP Tools: Provides a set of standardized tools for AI models to interact with WhatsApp, including search_contacts, list_messages, send_message, send_file, send_audio_message, and download_media.
Modular Architecture: Comprises a Go WhatsApp Bridge for API interaction and a Python MCP Server for AI integration.

Use Cases of WhatsApp MCP Server

AI-Powered WhatsApp Assistant: Build a personal AI assistant that can read, respond to, and manage your WhatsApp conversations.
Automated Customer Support: For small businesses, automate responses to common queries received via WhatsApp.
Data Analysis: Analyze your WhatsApp communication patterns, extract insights, or summarize long conversations using AI.
Personal Knowledge Base: Store and retrieve information from your WhatsApp chats, making it searchable and accessible through an AI.
Smart Notifications: Create custom notifications or triggers based on incoming WhatsApp messages.

FAQ from WhatsApp MCP Server

Q: What are the prerequisites for running WhatsApp MCP Server? A: You need Go, Python 3.6+, Anthropic Claude Desktop app (or Cursor), UV (Python package manager), and optionally FFmpeg.

Q: How do I authenticate my WhatsApp account? A: The first time you run the Go WhatsApp bridge, you will be prompted to scan a QR code with your WhatsApp mobile app.

Q: What if the QR code doesn't display or I have authentication issues? A: Try restarting the authentication script. Ensure your terminal supports displaying QR codes. If issues persist, check the MCP documentation for troubleshooting tips, including deleting database files to re-authenticate.

Q: Where is my WhatsApp data stored? A: All message history is stored locally in a SQLite database within the whatsapp-bridge/store/ directory.

Q: Can I send audio messages as WhatsApp voice messages? A: Yes, using the send_audio_message tool. For optimal compatibility, audio files should be in .ogg Opus format. FFmpeg can automatically convert other formats.

Q: How does media downloading work? A: By default, only metadata is stored. You use the download_media tool with message_id and chat_jid to download the actual media file, which then returns the local file path.

Q: What if I encounter Binary was compiled with 'CGO_ENABLED=0' error on Windows? A: This means CGO is disabled. You need to install a C compiler (e.g., via MSYS2) and enable CGO by running go env -w CGO_ENABLED=1 before running the Go application.

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.

WhatsApp MCP

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

Installation

Prerequisites

Go
Python 3.6+
Anthropic Claude Desktop app (or Cursor)
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.

Steps

Clone this repository

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

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

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

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 two 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 in SQLite. It serves as the bridge between WhatsApp and the MCP server.
Python MCP Server (whatsapp-mcp-server/): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with WhatsApp data and send/receive messages.

Data Storage

All message history is stored in a SQLite database within the whatsapp-bridge/store/ directory
The database maintains tables for chats and 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

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 which takes the message_id and chat_jid (which are shown when printing messages containing the meda), this downloads the media and then returns the file path which can be then opened or passed to another tool.

Technical Details

Claude sends requests to the Python MCP server
The MCP server queries the Go bridge for WhatsApp data or directly to the SQLite database
The Go accesses the WhatsApp API and keeps the SQLite 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

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.

WhatsApp MCP Server