Verified project record

lharries/whatsapp-mcp

An MCP server that connects AI agents such as Claude Desktop and Cursor to a personal WhatsApp account via the WhatsApp web multidevice API, enabling message search, contact lookup, media handling, and message sending with local SQLite storage. It runs as a self-hosted local bridge without requiring the paid WhatsApp Business API.

Project overview

Project type: MCP
Use cases: Automation
Deployment: Refer to project documentation
License: MIT

Best for

Developers who want an MCP-connected LLM to search, read, and interact with their personal WhatsApp messages, contacts, and media files using a local SQLite storage model.
Users who need a local-only, self-hosted bridge that connects to WhatsApp directly without requiring a paid WhatsApp Business API.

Key capabilities

Search and read personal WhatsApp messages, including images, videos, documents, and audio messages.
Search for WhatsApp contacts by name or phone number.
Send messages to individuals or groups, including media files such as images, videos, documents, and audio.
Stores all WhatsApp message history in a local SQLite database for searching and retrieval.
Authenticates directly with a personal WhatsApp account via the WhatsApp web multidevice API using a QR code.
Automatically converts non-Opus audio files to .ogg Opus format for playable WhatsApp voice messages if FFmpeg is installed.
Downloads media from WhatsApp messages and returns the local file path.

Limitations and risks

Running on Windows requires explicitly enabling CGO and having a C compiler installed.
Users might need to re-authenticate their WhatsApp session after approximately 20 days.
Project injection could lead to private data exfiltration due to the lethal trifecta vulnerability common in MCP servers.

Getting started

The setup difficulty is rated medium because it requires cloning the repository, installing multiple prerequisites, and manually configuring MCP client JSON files. The first success path is to clone the repository, run the WhatsApp bridge via 'go run main.go', scan the displayed QR code with the WhatsApp mobile app to authenticate, connect to the MCP server using UV, and restart the MCP client.

Evidence and sources

README: 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 messa…
README: - 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_) -…
README: 1. **Clone this repository** ```bash git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp ``` 2. **Run the WhatsApp bridge** Navigate to the whatsapp-bridge dire…
README: This application consists of two main components: 1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): A Go application that connects to WhatsApp's web API, handles authentication via…
README: 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 Window…

Reviewed at: 2026-07-16T16:16:34Z