# lharries/whatsapp-mcp architecture

> Architecture diagram of the GitHub repository lharries/whatsapp-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lharries/whatsapp-mcp
- Repository: https://github.com/lharries/whatsapp-mcp

## Overview

##### Components
a. WhatsApp – Not a component of the project itself, but note that the system connects to it via the multidevice API.
b. Go WhatsApp Bridge (located in the "whatsapp-bridge" directory)
- Manages connection to WhatsApp’s API.
- Handles authentication via QR code.
- Reads/writes to a local SQLite database (storing chat/message history).
c. SQLite Database (within whatsapp-bridge/store/)
- Contains tables for chats and messages.
- Used by the Go bridge for message history management.
d. Python MCP Server (located in the "whatsapp-mcp-server" directory)
- Implements the Multi-Client Protocol (MCP) for standardized interactions.
- Exposes methods like search_contacts, list_messages, send_message, and others, which are then used by Claude Desktop.
e. Claude Desktop (external integration)
- Sends requests into the MCP server.
- Receives data or directs message sending actions.

##### Relationships and Data Flow
- Claude Desktop sends API requests (e.g., for contact search, message retrieval, or sending direct messages) to the Python MCP Server.
- The Python MCP Server processes these requests and, as needed, queries the SQLite database directly or interacts with the Go WhatsApp Bridge.
- The Go WhatsApp Bridge actively maintains the connection to WhatsApp, processes QR code authentication, fetches updates, synchronizes message history, and ensures that new messages are persisted into the SQLite database.
- Data flows “upstream” from the Go bridge (and database) to the MCP server and then back through to Claude Desktop.
- For outgoing messages, the direction is reversed: originating from Claude Desktop to the MCP server, then forwarded to the Go bridge, which then communicates with WhatsApp.

##### Important Architectural Patterns and Design Principles
- Separation of concerns: The Go application is solely responsible for WhatsApp connections and local storage via SQLite, while the Python MCP Server deals with protocol handling and integration with Claude.
- API-centric communication: Clear request-response channels defined for Claude’s tool access, encapsulated in the MCP protocols.
- Decoupling via a database intermediary: Ensuring that message storage resides within SQLite, allowing both components to access current state as needed.
- Authentication management: Includes handling re-authentication based on WhatsApp’s device policies.

##### Relevant Technologies, Frameworks, and Libraries
- Go programming language (for the WhatsApp Bridge) using the whatsmeow library.
- Python (for the MCP Server) along with its dependency configurations (pyproject.toml, uv.lock).
- SQLite database for local message storage.
- Integration with Anthropic Claude Desktop via a configuration that links to the MCP Server.
- UV as a Python package manager for deployment.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    subgraph "External Systems"
        WA["WhatsApp API"]:::external
        CD["Claude Desktop"]:::external
    end

    %% Internal Components
    subgraph "Internal Components"
        subgraph "WhatsApp Integration"
            GWB["Go WhatsApp Bridge"]:::internal
            DB["SQLite Database"]:::database
            GWB -->|"Store/Query"| DB
            DB -->|"RetrieveData"| GWB
        end
        PMCP["Python MCP Server"]:::internal
    end

    %% Data Flow Connections
    WA -->|"Authenticate/FetchMsgs"| GWB
    GWB -->|"Sync/Updates"| PMCP
    PMCP -->|"Command/Query"| GWB
    PMCP -->|"DataReadWrite"| DB
    CD -->|"MCPAPIRequests"| PMCP
    PMCP -->|"SendMessage"| GWB

    %% Click Events for Component Mapping
    click GWB "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-bridge/main.go"
    click GWB "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-bridge/go.mod"
    click GWB "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-bridge/go.sum"
    click PMCP "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-mcp-server/main.py"
    click PMCP "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-mcp-server/whatsapp.py"
    click PMCP "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-mcp-server/pyproject.toml"
    click PMCP "https://github.com/lharries/whatsapp-mcp/blob/main/whatsapp-mcp-server/uv.lock"

    %% Styles
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef internal fill:#ccf,stroke:#333,stroke-width:2px;
    classDef database fill:#ffc,stroke:#333,stroke-width:2px;
```
