whatsapp-mcp

What it is

WhatsApp MCP Server is a Model Context Protocol (MCP) server that interacts with a personal WhatsApp account through a Go bridge and a Python MCP server. It enables searching contacts, listing chats and messages, and sending messages or media to individuals or groups. All messages are stored locally in SQLite and are only exposed to an external AI tool when accessed via configured MCP tools.

How it works

• The Go bridge connects to WhatsApp via the Whatsmeow-based web API, authenticates with a QR code, and stores message history in a SQLite database.
• The Python MCP server exposes standardized tools for Claude to interact with WhatsApp data (search_contacts, list_messages, list_chats, get_chat, get_direct_chat_by_contact, get_contact_chats, get_last_interaction, get_message_context, send_message, send_file, send_audio_message, download_media).
• Data flows: Claude -> Python MCP server -> Go bridge -> WhatsApp; and data is stored in whatsapp-bridge/store.

Getting started

• Prerequisites include Go, Python 3.6+, Anthropic Claude Desktop app (or Cursor), UV, and FFmpeg (optional for audio).
• Steps include cloning the repo, running the WhatsApp bridge with the provided commands, and configuring Claude or Cursor with the JSON/mcp.json path as described.
• Windows users: CGO must be enabled for go-sqlite3; instructions are provided to install a C compiler and enable CGO.

Getting started (commands from README)

• Clone the repository:

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

• Run the WhatsApp bridge:

cd whatsapp-bridge
go run main.go

• Connect to the MCP server by providing the JSON configuration:

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

• Claude Desktop path:

~/Library/Application Support/Claude/claude_desktop_config.json

• Cursor path:

~/.cursor/mcp.json

Recent releases

• v0.0.1 (2025-04-06): Groups and media file support; sending/receiving media files (audio, video, images); improved Windows instructions.

Traction

• Stars: 6060
• Forks: 1215
• Open issues: 221

Caveats

• License: MIT
• Created: 2025-03-29
• Last push: 2025-07-13
• Notes include caution about the lethal trifecta and potential private data exposure when injected; read MCP documentation for troubleshooting.