Whatsapp MCP

What lharries/whatsapp-mcp MCP server does

The lharries/whatsapp-mcp MCP server provides MCP tools for working with a personal WhatsApp account. It can search contacts by name or phone number, inspect chats and messages, find recent interactions, and retrieve context around a specific message. It also supports sending text messages to individual recipients or groups identified by a group JID.

Media is supported in both directions. The server can send images, videos, documents, and audio files, and it can download media associated with a message. Audio can be sent as a playable WhatsApp voice message when the input is OGG Opus or when FFmpeg is available to convert another format. Without FFmpeg, audio can still be sent as a regular file.

How it works

The project has two cooperating processes. A Go bridge connects to WhatsApp's web multidevice API through the whatsmeow library. It handles the WhatsApp session, receives updates, and stores chats and messages in SQLite under whatsapp-bridge/store/. A separate Python MCP server exposes the agent-facing tools.

Requests from Claude or Cursor go to the Python process. Depending on the operation, that process queries the bridge or the local SQLite database. Outbound messages and files are passed through the bridge to WhatsApp. Message history is kept on the local machine and is sent to the language model only when an agent uses a tool to access it.

Setup and configuration

The lharries/whatsapp-mcp MCP server is run from a cloned repository rather than installed as a standalone package. Go and Python 3.6 or newer are prerequisites. UV is used to launch the Python MCP server, while the Go bridge is started with go run main.go from the whatsapp-bridge directory.

On first launch, the bridge displays a QR code for authentication. Scan it with the WhatsApp mobile application. Existing sessions can reconnect automatically, although re-authentication may be needed after roughly 20 days. The README provides MCP configuration examples for Claude Desktop and Cursor; those entries use UV with the repository's whatsapp-mcp-server directory and main.py.

Both processes need to remain available for the integration to work. FFmpeg is optional and is only needed for automatic conversion of audio into playable voice-message format. On Windows, the SQLite dependency requires CGO and a C compiler; the documented setup enables CGO before starting the bridge.

Tools and capabilities

The documented tools include:

• search_contacts for contact lookup.
• list_chats, get_chat, and contact-specific chat lookups for navigating conversations.
• list_messages, get_last_interaction, and get_message_context for retrieving message history.
• send_message for text messages to phone numbers or group JIDs.
• send_file for images, videos, documents, and raw audio.
• send_audio_message for WhatsApp voice messages.
• download_media for obtaining a local path to media attached to a message.

Media metadata is stored by default. The actual media file is downloaded only when download_media is called with the relevant message ID and chat JID.

Limitations and notes

The lharries/whatsapp-mcp MCP server operates on a personal WhatsApp account and depends on WhatsApp's linked-device limits and session state. Initial history synchronization can take several minutes. If the bridge becomes out of sync, the documented recovery method is to delete the two SQLite database files in whatsapp-bridge/store/ and authenticate again.

Because an agent can access private messages and send outbound content, permissions and prompt-injection risks should be considered before connecting it to an account. The repository specifically warns that malicious instructions in project content could result in private data being exfiltrated. On Windows, failing to enable CGO or install a compatible compiler can prevent the bridge from working.