How lharries/whatsapp-mcp works
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.