WhatsApp Communication Proxy Server

This repository represents a derivative work based on lharries/whatsapp-mcp, adapted to support a publicly exposed MCP server endpoint. You are authorized to share this server URL with vetted external entities to grant them operational access to your WhatsApp account.

This setup empowers both you and authorized third parties to execute comprehensive searches across your proprietary WhatsApp message history, query your contact directory, and initiate message broadcasts to either single recipients or defined groups.

It interfaces straight with your private WhatsApp deployment through the WhatsApp web multi-device framework (leveraging the whatsmeow underpinning library). All transmitted and received data is persisted locally within an SQLite repository, and is only channeled to a Large Language Model (like Claude) when explicitly invoked via controlled agent tooling.

Setup Procedure

Prerequisites

• Go programming language environment
• Python interpreter version 3.6 or higher
• Anthropic Claude Desktop application (or Cursor IDE)
• UV package manager for Python; installation command: curl -LsSf https://astral.sh/uv/install.sh | sh

Execution Steps

1. Repository Acquisition

bash git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp

1. Launching the WhatsApp Intermediary (Bridge)

Navigate into the whatsapp-bridge subdirectory and execute the Go binary:

bash cd whatsapp-bridge go run main.go

Upon the initial launch, a QR code visualization will appear. Use your WhatsApp mobile application to scan this code for session authentication. Note: Re-authentication may be periodically required (approx. every three weeks).

1. Configuring the MCP Interface Server

Obtain your authentication secret from the ngrok dashboard and initiate the MCP server component:

bash cd whatsapp-mcp-server uv run main.py

When prompted, input the ngrok secret token. Crucially, record the public URL displayed in the console output.

SECURITY ALERT: TREAT THIS EXPOSED URL AS HIGHLY CONFIDENTIAL

System Component Breakdown

This system is architected around two primary, interacting modules:

1. Go WhatsApp Linker (whatsapp-bridge/): This Go binary module establishes the persistent connection to WhatsApp's web interface API, manages the QR-based handshake, and serializes message history into SQLite storage. It functions as the primary conduit between WhatsApp and the MCP server layer.

2. Python MCP Host (whatsapp-mcp-server/): This Python application implements the Model Context Protocol (MCP) specification, furnishing standardized interfaces (tools) for Claude to query WhatsApp artifacts and issue outbound messages.

Data Persistence Layer

• All conversational records are retained in an SQLite database located within whatsapp-bridge/store/.
• The database schema includes dedicated tables for chat metadata and individual message entries.
• Messages are internally indexed to optimize rapid search and retrieval operations.

Operational Use Cases

Once the connection is fully established, users can direct Claude to manage WhatsApp interactions, exploiting the LLM's analytical strengths within their messaging environment.

Available MCP Toolset

Claude is equipped to utilize the following functions to manipulate WhatsApp data:

• search_contacts: Locate directory entries via name or telephone identifier.
• list_messages: Fetch message records, supporting optional filtering parameters.
• list_chats: Retrieve a manifest of all active conversations along with associated details.
• get_chat: Obtain granular data for a specific conversation thread.
• get_direct_chat_by_contact: Resolve the direct thread associated with a known contact.
• get_contact_chats: Enumerate all threads involving a specified participant.
• get_last_interaction: Fetch the most recent communication timestamp with a contact.
• get_message_context: Retrieve preceding and succeeding messages relative to a target message.
• send_message: Transmit a new message payload to a designated recipient number.

Data Flow Mechanics

1. The external agent (Claude) submits operational requests to the Python MCP host.
2. The MCP host either consults the Go linker for live WhatsApp data or queries the local SQLite store directly.
3. The Go linker handles API calls to WhatsApp and maintains the transactional integrity of the SQLite repository.
4. Results propagate back up the chain via the MCP host.
5. Outbound messaging proceeds from the external caller, through the MCP server, to the Go linker, and finally to the WhatsApp network.

Debugging Guidance

• Installation Permissions: If uv execution fails due to permissions, ensure the utility path is correctly set in your environment variables or invoke the executable using its absolute location.
• Service Dependency: Both the Go intermediary and the Python server must be running concurrently for integration to function.

Connection Authentication Troubleshooting

• QR Code Visibility Failure: Restart the authentication script. If the issue persists, verify that your terminal emulator supports displaying ANSI QR codes.
• Existing Session: If the session is already valid, the Go linker will automatically establish the connection without prompting for a QR scan.
• Device Cap Exceeded: WhatsApp imposes a ceiling on linked devices. You must manually revoke access for an existing device via your mobile phone settings (Settings > Linked Devices).
• Data Lag Post-Auth: Initial history synchronization may require several minutes, particularly for accounts with voluminous archives.
• Data Desynchronization: Should the bridge's state diverge from your phone's WhatsApp state, eliminate the database files (whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db) and restart the linker to force a full re-authentication.