cleanup

2026-03-10 08:51:23 +00:00 · 2025-03-30 00:30:44 +00:00
commit 76d332bae7
12 changed files with 2169 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,135 @@
+# WhatsApp MCP Server
+
+This is a Model Context Protocol (MCP) server for WhatsApp.
+
+With this you can search you personal Whatsapp messages, search your contacts and send messages.
+
+It connects to your **personal WhatsApp account** directly via the Whatsapp web multidevice API (using the [whatsmeow](https://github.com/tulir/whatsmeow) library). All your messages are stored locally in a SQLite database and only sent to an LLM (such as Claude) when the agent accesses them through tools (which you control).
+
+Here's an example of what you can do when it's connected to Claude.
+
+![WhatsApp MCP](./example-use.png)
+
+## Installation
+
+### Prerequisites
+
+- Go
+- Python 3.6+
+- Anthropic Claude Desktop app (or Cursor)
+- UV (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+### Steps
+
+1. **Clone this repository**
+
+   ```bash
+   git clone https://github.com/lharries/whatsapp-mcp.git
+   cd whatsapp-mcp
+   ```
+
+2. **Run the WhatsApp bridge**
+
+   Navigate to the whatsapp-bridge directory and run the Go application:
+
+   ```bash
+   cd whatsapp-bridge
+   go run main.go
+   ```
+
+   The first time you run it, you will be prompted to scan a QR code. Scan the QR code with your WhatsApp mobile app to authenticate.
+
+   After approximately 20 days, you will might need to re-authenticate.
+
+3. **Connect to the the MCP server**
+
+   Copy the below json with the appropriate {{PATH}} values:
+
+   ```json
+   {
+     "mcpServers": {
+       "whatsapp": {
+         "command": "{{PATH}}/.local/bin/uv", // Run `which uv` and place the output here
+         "args": [
+           "--directory",
+           "{{PATH}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
+           "run",
+           "main.py"
+         ]
+       }
+     }
+   }
+   ```
+
+   For **Claude**, save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:
+
+   ```
+   ~/Library/Application Support/Claude/claude_desktop_config.json
+   ```
+
+   For **Cursor**, save this as `mcp.json` in your Cursor configuration directory at:
+
+   ```
+   ~/.cursor/mcp.json
+   ```
+
+4. **Restart Claude Desktop / Cursor**
+
+   Open Claude Desktop and you should now see WhatsApp as an available integration.
+
+   Or restart Cursor.
+
+## Architecture Overview
+
+This application consists of two main components:
+
+1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): A Go application that connects to WhatsApp's web API, handles authentication via QR code, and stores message history in SQLite. It serves as the bridge between WhatsApp and the MCP server.
+
+2. **Python MCP Server** (`whatsapp-mcp-server/`): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with WhatsApp data and send/receive messages.
+
+### Data Storage
+
+- All message history is stored in a SQLite database within the `whatsapp-bridge/store/` directory
+- The database maintains tables for chats and messages
+- Messages are indexed for efficient searching and retrieval
+
+## Usage
+
+Once connected, you can interact with your WhatsApp contacts through Claude, leveraging Claude's AI capabilities in your WhatsApp conversations.
+
+### MCP Tools
+
+Claude can access the following tools to interact with WhatsApp:
+
+- **search_contacts**: Search for contacts by name or phone number
+- **list_messages**: Retrieve messages with optional filters and context
+- **list_chats**: List available chats with metadata
+- **get_chat**: Get information about a specific chat
+- **get_direct_chat_by_contact**: Find a direct chat with a specific contact
+- **get_contact_chats**: List all chats involving a specific contact
+- **get_last_interaction**: Get the most recent message with a contact
+- **get_message_context**: Retrieve context around a specific message
+- **send_message**: Send a WhatsApp message to a specified phone number
+
+## Technical Details
+
+1. Claude sends requests to the Python MCP server
+2. The MCP server queries the Go bridge for WhatsApp data or directly to the SQLite database
+3. The Go accesses the WhatsApp API and keeps the SQLite database up to date
+4. Data flows back through the chain to Claude
+5. When sending messages, the request flows from Claude through the MCP server to the Go bridge and to WhatsApp
+
+## Troubleshooting
+
+- If you encounter permission issues when running uv, you may need to add it to your PATH or use the full path to the executable.
+- Make sure both the Go application and the Python server are running for the integration to work properly.
+
+### Authentication Issues
+
+- **QR Code Not Displaying**: If the QR code doesn't appear, try restarting the authentication script. If issues persist, check if your terminal supports displaying QR codes.
+- **WhatsApp Already Logged In**: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.
+- **Device Limit Reached**: WhatsApp limits the number of linked devices. If you reach this limit, you'll need to remove an existing device from WhatsApp on your phone (Settings > Linked Devices).
+- **No Messages Loading**: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.
+- **WhatsApp Out of Sync**: If your WhatsApp messages get out of sync with the bridge, delete both database files (`whatsapp-bridge/store/messages.db` and `whatsapp-bridge/store/whatsapp.db`) and restart the bridge to re-authenticate.
+
+For additional Claude Desktop integration troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues). The documentation includes helpful tips for checking logs and resolving common issues.