Home / MCP / WhatsApp MCP Server

WhatsApp MCP Server

Exposes a MCP server to search, read, and send WhatsApp messages and media via Claude

python

5.1kstars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "whatsapp": {
            "command": "uv",
            "args": [
                "--directory",
                "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
                "run",
                "main.py"
            ]
        }
    }
}

You run a MCP server that lets Claude access and control your WhatsApp data, enabling you to search messages, read chats, and send media or texts directly through AI-assisted workflows. All data is stored locally and remains under your control, with careful separation between data storage and AI processing.

How to use

Once your MCP server is running, you connect an MCP client (such as Claude) to access WhatsApp data and actions. You can search contacts, list and read messages, view chats, and perform messaging actions like sending text and media. Media can be downloaded when you need to access the actual file, and audio messages can be sent as playable WhatsApp voice messages when available formats and tools are present.

How to install

Prerequisites include the Go programming language, Python 3.6 or newer, the UV package manager, and optional FFmpeg for audio processing.

Follow these concrete steps to set up the server and connect your MCP client:

# 1) Clone the project
git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp

# 2) Run the WhatsApp bridge (Go application)
cd whatsapp-bridge
go run main.go

# The first run will prompt you to scan a QR code with WhatsApp. Scan it with your phone.
# Re-authentication may be required periodically.

# 3) Prepare the MCP server config (stdio/mcp config)
# The MCP command uses UV to run the Python MCP server component.
# Use the provided placeholder paths to construct the command in your environment.

# 4) Start the MCP integration from your client (Claude/Cursor) by using the following config (see the example below)

Additional configuration and usage notes

Media handling supports sending images, videos, documents, and audio. To send audio as playable voice messages, ensure the audio is in .ogg Opus format or use FFmpeg to convert other formats automatically. You can download media from messages when needed to view or reuse the local file paths.

Troubleshooting and notes

If you encounter permissions or environment path issues with the MCP runtime, ensure the UV executable is on your PATH or reference its full path. Make sure both the Go bridge and the Python MCP server are running for the integration to work. If you need to re-authenticate the WhatsApp bridge, restart the bridge and scan a new QR code.

MCP Tools

Claude can access the following tools to interact with WhatsApp data and actions.

Available tools

search_contacts

Search for contacts by name or phone number to start a conversation or find relevant chats.

list_messages

Retrieve messages with optional filters and context to understand recent activity in a chat.

list_chats

List available chats with metadata such as chat type and participant counts.

get_chat

Fetch information about a specific chat, including participants and history scope.

get_direct_chat_by_contact

Find the direct chat with a specific contact to query or message them directly.

get_contact_chats

List all chats involving a particular contact for quick context.

get_last_interaction

Return the most recent message exchanged with a given contact.

get_message_context

Retrieve surrounding messages to provide context for a specific message.

send_message

Send a text message to a specified phone number or group JID.

send_file

Send a file (image, video, raw audio, or document) to a recipient or group.

send_audio_message

Send an audio file as a playable WhatsApp voice message (requires .ogg Opus or FFmpeg for conversion).

download_media

Download media from a message and obtain the local file path for use in tools.