lharries/whatsapp-mcp

Free

用于搜索个人 WhatsApp 消息、联系人以及向个人或群组发送消息的 MCP 服务器。

FreeFree tier

Inputs: text, audioOutputs: text, audio

Type

Open Source

Visit Website GitHub (40 stars)

About lharries/whatsapp-mcp

The WhatsApp MCP server is an open-source implementation of the Model Context Protocol (MCP) that enables AI assistants like Claude to interact with a user's personal WhatsApp account. It allows searching and reading WhatsApp messages (including text, images, videos, documents, and audio), searching contacts, and sending messages to individuals or groups. The server connects directly via the WhatsApp web multidevice API using the whatsmeow library, stores all messages locally in a SQLite database, and only exposes data to the LLM when explicitly accessed through tools. It requires Go, Python 3.6+, UV, and optionally FFmpeg for audio conversion. Users authenticate by scanning a QR code with the WhatsApp mobile app. The server is designed for integration with Claude Desktop or Cursor.

Key Features

Search personal WhatsApp messages including text, images, videos, documents, and audio

Read message content such as text, images, videos, documents, and audio messages

Search contacts from your WhatsApp account

Send messages to individuals or groups

Send media files including images, videos, documents, and audio

Stores all messages locally in a SQLite database for privacy

Uses WhatsApp web multidevice API via the whatsmeow library

Integrates with Claude Desktop and Cursor via MCP protocol

Optional FFmpeg for automatic audio format conversion to Ogg Opus

Pros & Cons

Pros

Open source and free to use
Local storage of messages ensures privacy (data only sent to LLM when tools are called)
Supports multiple media types (images, videos, documents, audio)
Easy integration with popular AI tools like Claude Desktop and Cursor
Active GitHub repository with regular updates

Cons

Requires re-authentication every ~20 days
Windows compatibility requires manual setup of CGO and a C compiler
Project injection vulnerability could lead to private data exfiltration (as noted in the repository)
Not an official WhatsApp Business API; limited to personal accounts
Technical setup required (Go, Python, UV, FFmpeg optional)

Best For

Query personal WhatsApp message history using an AI assistantAutomate sending messages or media to specific contacts or groupsRetrieve and analyze image, video, or document content from chatsSearch through large volumes of messages to find relevant information

FAQ

What is the WhatsApp MCP server?

It is a Model Context Protocol (MCP) server that allows AI assistants like Claude to search, read, and send WhatsApp messages and media through your personal WhatsApp account.

Is this an official WhatsApp API?

No, it uses the WhatsApp web multidevice API via the whatsmeow library and connects to your personal WhatsApp account, not a business API.

How are messages stored?

All messages are stored locally in a SQLite database on your machine and are only sent to the LLM when the agent accesses them through tools (which you control).

What are the system requirements?

Go, Python 3.6+, UV (Python package manager), and optionally FFmpeg for audio conversion. For Windows, you need a C compiler and CGO enabled.

How do I authenticate?

Run the WhatsApp bridge (Go application) and scan the QR code with your WhatsApp mobile app. You may need to re-authenticate after approximately 20 days.

Can I send media files?

Yes, you can send images, videos, documents, and audio messages. For audio, FFmpeg is needed to convert non-Opus files to Ogg Opus format for playback as voice messages.