Seamless WhatsApp Integration with LLMs: A Comprehensive Guide to the Model Context Protocol (MCP) Server

Unlock the power of Large Language Models (LLMs) like Claude by connecting them directly to your WhatsApp account. This guide provides a detailed walkthrough of setting up a Model Context Protocol (MCP) server for WhatsApp, enabling you to search, read, and interact with your personal messages, contacts, and media files through an AI-powered interface.

This integration leverages the WhatsApp Web Multi-Device API via the whatsmeow library, ensuring a direct connection to your personal WhatsApp account. All your messages are stored locally in a SQLite database, guaranteeing privacy and control over your data. Information is only shared with the LLM when explicitly accessed through the MCP tools.

WhatsApp MCP

Prerequisites

Before you begin, ensure you have the following installed:

Go: The Go programming language is required for running the WhatsApp bridge.
Python 3.6+: Python is necessary for the MCP server.
Anthropic Claude Desktop App (or Cursor): This is the LLM platform that will interface with your WhatsApp data.
UV (Python Package Manager): Install with curl -LsSf https://astral.sh/uv/install.sh | sh. UV is used for managing Python dependencies.
FFmpeg (Optional): Required for converting audio files to the .ogg Opus format for sending voice messages. If not installed, you can still send raw audio files using the send_file tool.

Installation Steps

Follow these steps to set up the WhatsApp MCP server:

Clone the Repository:

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

Run the WhatsApp Bridge:

Navigate to the whatsapp-bridge directory and execute the Go application:
```
cd whatsapp-bridge
go run main.go
```
The first time you run this, you'll be prompted to scan a QR code using your WhatsApp mobile app. This authenticates the connection. Note that re-authentication may be required approximately every 20 days.

Configure the MCP Server:

Create a JSON configuration file for Claude or Cursor, replacing the placeholder paths with your actual paths:

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and paste 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: ~/Library/Application Support/Claude/claude_desktop_config.json
For Cursor: Save this as mcp.json in your Cursor configuration directory: ~/.cursor/mcp.json

Restart Claude Desktop / Cursor:

Restart your LLM platform to activate the WhatsApp integration. You should now see WhatsApp as an available integration option.

Windows Compatibility

Running this project on Windows requires enabling CGO and installing a C compiler due to the go-sqlite3 dependency.

Install a C Compiler:

We recommend using MSYS2. After installation, add the ucrt64\bin folder to your PATH. A detailed guide is available here.

Enable CGO and Run the App:

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

Architecture Overview

The application comprises two key components:

Go WhatsApp Bridge (whatsapp-bridge/): This Go application manages the connection to the WhatsApp Web API, handles authentication, and stores message history in a SQLite database. It acts as the intermediary between WhatsApp and the MCP server.
Python MCP Server (whatsapp-mcp-server/): This Python server implements the Model Context Protocol (MCP), providing a standardized interface for LLMs like Claude to interact with WhatsApp data and send/receive messages.

Data Storage

All message history is stored in a SQLite database located in the whatsapp-bridge/store/ directory. The database contains tables for chats and messages, with messages indexed for efficient searching and retrieval.

Usage

Once connected, you can interact with your WhatsApp contacts through Claude, leveraging its AI capabilities to enhance your 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 sending and receiving various media types:

Media Sending

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, only the metadata of the media is stored in the local database. To access the actual media file, use the download_media tool, providing the message_id and chat_jid (obtained from the message metadata). This downloads the media and returns the file path.

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 bridge 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

UV Permission Issues: If you encounter permission issues when running UV, ensure it's added to your PATH or use the full path to the executable.
Integration Not Working: Verify that both the Go application and the Python server are running for the integration to function correctly.

Authentication Issues

QR Code Not Displaying: Restart the authentication script. If the issue persists, check if your terminal supports displaying QR codes.
WhatsApp Already Logged In: The Go bridge will automatically reconnect without showing a QR code if your session is already active.
Device Limit Reached: WhatsApp limits the number of linked devices. Remove an existing device from WhatsApp on your phone (Settings > Linked Devices).
No Messages Loading: Allow several minutes for your message history to load after initial authentication, especially if you have many chats.
WhatsApp Out of Sync: Delete both database files (whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db) and restart the bridge to re-authenticate if your WhatsApp messages get out of sync with the bridge.

For additional Claude Desktop integration troubleshooting, refer to the MCP documentation. This resource provides helpful tips for checking logs and resolving common issues.