WhatsApp MCP Server: Claude WhatsApp Access
/whatsapp-mcp
WhatsApp MCP Server is worth using if you want Claude or Cursor to work with your personal WhatsApp account, but its private-data exposure and two-process setup demand care. The tools are focused and useful; the README’s project-injection warning is the deciding drawback.
What the WhatsApp MCP Server does
WhatsApp MCP Server is a Model Context Protocol integration that connects Claude Desktop or Cursor to a personal WhatsApp account through the WhatsApp web multidevice API. Its Go bridge keeps chat and message data in local SQLite, while its Python server exposes MCP tools for searching, reading, downloading, and sending WhatsApp content.
Why it was built
WhatsApp MCP Server was built so Claude can access and send personal WhatsApp content without manually moving messages between WhatsApp and the AI client. It fills a specific messaging gap by letting an agent search chats and contacts, inspect message context, download media, and deliver text or files through MCP tools.
WhatsApp and media tools
- ✓WhatsApp MCP Server exposes tools for finding contacts by name or phone number, listing chats, opening a specific chat, and reviewing recent interactions.
- ✓WhatsApp MCP Server can list messages with filters, retrieve surrounding context, and search indexed history stored in the local SQLite database.
- ✓Messages can be sent to an individual phone number or group JID through dedicated text and file-sending tools.
- ✓Media handling covers images, videos, documents, raw audio, and playable voice messages. Voice notes use .ogg Opus, with FFmpeg able to convert other audio formats.
- ✓WhatsApp MCP Server can download media on demand and return its local path; until then, the database retains message metadata rather than the downloaded file.
- ✓The architecture separates a Go WhatsApp bridge from a Python MCP server. The bridge maintains the account connection and SQLite data, while the server exposes the tools used by Claude Desktop or Cursor.
Install the bridge and MCP server
WhatsApp MCP Server is installed manually rather than through a marketplace. Clone the repository, install Go, Python 3.6+, and UV, then run `cd whatsapp-bridge && go run main.go` and scan the QR authentication code with WhatsApp. Add the Python MCP entry to Claude Desktop or Cursor using the documented `uv --directory ... run main.py` configuration, then restart the host. Both processes must remain running. On Windows, CGO must be enabled and a C compiler installed; MSYS2 is recommended. Host-version requirements are not clearly documented.
Who should use it
WhatsApp MCP Server suits people who regularly use Claude Desktop or Cursor and want an AI assistant to retrieve context from or send content through their own personal WhatsApp account. It is less suitable for users who need a hosted business integration, strict message-isolation guarantees, or a one-command installation.
Strengths
- ✓Stores message history locally in SQLite and sends content to an LLM only when an agent accesses it through controlled tools.
- ✓The Go bridge connects directly to a personal WhatsApp account through the web multidevice API, with QR-code authentication and automatic reconnection.
- ✓The MCP tools cover both sides of the workflow: searching chats and contacts, retrieving message context, sending messages, and sending or downloading media.
- ✓The two-process architecture cleanly separates WhatsApp access and local storage from the Python MCP interface used by Claude Desktop or Cursor.
- ✓Media handling is practical: `send_file` handles documents and media, while `send_audio_message` can convert audio into `.ogg` Opus with FFmpeg installed.
Privacy, security, and setup limits
- △The README warns that project injection could expose private data through this class of MCP integration. Local SQLite storage does not remove that risk because an agent can invoke tools that disclose messages or media.
- △WhatsApp MCP Server requires Go, Python, UV, a separately running Go bridge, a Python MCP process, and host configuration. Windows users also need CGO and a C compiler.
- △QR authentication can expire, with re-authentication needed after approximately 20 days. WhatsApp’s linked-device limit may also require removing an existing linked device.
- △Message history can take several minutes to load after the initial authentication, particularly for accounts with many chats.
- △Media remains metadata-only in the database by default; files must be downloaded explicitly before another tool can access their local path.
Alternatives to consider
FAQ
Commercial use is allowed under the MIT license covering WhatsApp MCP Server. The license permits commercial use, modification, distribution, and private use, subject to its attribution and notice requirements.
The WhatsApp MCP Server does not use the official WhatsApp Business API. It connects to a personal account through the WhatsApp web multidevice API using the whatsmeow library.
WhatsApp MCP Server stores message history in a local SQLite database under the `whatsapp-bridge/store/` directory. Message content reaches an LLM only when an agent accesses it through one of the configured MCP tools.
WhatsApp MCP Server is documented for Anthropic’s Claude Desktop app and Cursor. Each host uses an MCP configuration entry that launches the Python server from the cloned repository.
WhatsApp MCP Server can send images, videos, documents, and audio. Playable voice messages require .ogg Opus input or FFmpeg for conversion; without FFmpeg, audio can still be sent as a raw file.
WhatsApp MCP Server requires Go, Python 3.6+, UV, and either Claude Desktop or Cursor. FFmpeg is optional but needed to convert audio into playable voice messages. Windows also requires CGO and a C compiler.
Best use cases
- •Find a previous decision made in a WhatsApp chat without searching manually.
- •Let Claude review recent conversations with a particular contact before answering a question.
- •Send a prepared document, image, video, or voice note to an individual or group.
- •Retrieve an older shared file by locating its message and downloading it locally.
- •Manage personal WhatsApp follow-ups through Claude Desktop or Cursor while keeping the message database on the local machine.
Related repositories
Still deciding about whatsapp-mcp?
One click hands the question to an AI along with this page — see what it says about whatsapp-mcp.