whatsapp-mcp by iamveene - MCP Server

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).

Features

Authentication: QR code-based WhatsApp Web authentication
Send Messages: Text, images, videos, audio (voice notes), documents
Receive Messages: Real-time message reception with history sync
Interactive Messages: Full support for list menus, buttons, and native flow messages
Menu Selection: API endpoint to respond to interactive menus
Media Download: Download media from received messages
Session Persistence: SQLite-based session storage with auto-reconnection

Quick Start

Using Docker

docker build -t whatsapp-mcp . 
docker run -d --name whatsapp-mcp \
  -p 8080:8080 \
  -v $(pwd)/store:/app/store \
  whatsapp-mcp

Building from Source

go build -o whatsapp-bridge . 
./whatsapp-bridge -port 8080

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/iamveene/whatsapp-mcp.git
cd whatsapp-mcp

Run the 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.

API Endpoints

Health Check

GET /api/health

QR Code (for authentication)

GET /api/qr-code

Send Message

POST /api/send
Content-Type: application/json

{
  "recipient": "5527999999999",
  "message": "Hello!",
  "media_path": "/path/to/file.jpg"  // optional
}

Select Menu Option

POST /api/select-option
Content-Type: application/json

{
  "recipient": "180216945205454@lid",
  "selected_id": "Option1",
  "selected_text": "Option 1 Text",  // optional
  "response_type": "native_flow"     // list, buttons, or native_flow (default)
}

Download Media

POST /api/download
Content-Type: application/json

{
  "message_id": "ABC123",
  "chat_jid": "5527999999999@s.whatsapp.net"
}

Interactive Messages

This server fully supports WhatsApp interactive messages, including:

Receiving Interactive Messages

Interactive messages are stored as JSON in the message content field:

List Message Example:

{
  "type": "list",
  "header": "Menu Title",
  "body": "Select an option:",
  "footer": "Powered by Bot",
  "sections": [
    {
      "title": "Section 1",
      "rows": [
        {"id": "opt1", "title": "Option 1", "description": "Description 1"},
        {"id": "opt2", "title": "Option 2", "description": "Description 2"}
      ]
    }
  ]
}

Responding to Interactive Messages

Use the /api/select-option endpoint to respond to menus:

curl -X POST http://localhost:8080/api/select-option \
  -H "Content-Type: application/json" \
  -d 
  {
    "recipient": "180216945205454@lid",
    "selected_id": "UnimedVitória",
    "response_type": "native_flow"
  }

Architecture Overview

This application consists of two main components:

Go 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: A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with WhatsApp data and send/receive messages.

Troubleshooting

If your WhatsApp messages get out of sync with the bridge, delete both database files (store/messages.db and store/whatsapp.db) and restart the bridge to re-authenticate.

License

MIT License