whatsapp-mcp

Sending Media

• Files (Images, Videos, Documents): Use the send_file tool.
• Voice Messages: Use the send_audio_message tool. For best results, use .ogg Opus files. If FFmpeg is installed, the server will automatically convert other formats (MP3, WAV, etc.) to Opus. Without FFmpeg, you must use send_file to send raw audio files, but they will not appear as playable voice messages.

Downloading Media

By default, the local database only stores media metadata. To access the actual file, use the download_media tool. You will need the message_id and chat_jid (provided in the message metadata) to download the media and retrieve its local file path.

Running this project on Windows requires enabling CGO because go-sqlite3 depends on it.

1. Install a C compiler: Use MSYS2 and ensure the ucrt64\bin folder is added to your PATH.
2. Enable CGO and run: Run the following commands in your terminal:

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go

To install the WhatsApp MCP server, follow these steps:

1. Clone the repository:

   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. You will be prompted to scan a QR code with your WhatsApp mobile app to authenticate.

   cd whatsapp-bridge
   go run main.go

3. Connect to the MCP server: Configure your MCP client (Claude Desktop or Cursor) by adding the server configuration. You must replace {{PATH_TO_UV}} with the output of which uv and {{PATH_TO_SRC}} with the absolute path to the repository.

4. Restart your client: Restart Claude Desktop or Cursor to enable the WhatsApp integration.

To use WhatsApp with Claude Desktop, save the following JSON configuration to ~/Library/Application Support/Claude/claude_desktop_config.json.

Note: You must replace {{PATH_TO_UV}} with the result of which uv and {{PATH_TO_SRC}} with the absolute path to the repository root, appending /whatsapp-mcp-server to that path.

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

To use WhatsApp with Cursor, save the following JSON configuration to your Cursor configuration directory at ~/.cursor/mcp.json.

Note: You must replace {{PATH_TO_UV}} with the result of which uv and {{PATH_TO_SRC}} with the absolute path to the repository root, appending /whatsapp-mcp-server to that path.

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

Authentication Issues

• QR Code Not Displaying: Restart the authentication script or check if your terminal supports QR code rendering.
• Device Limit Reached: Remove an existing device in WhatsApp (Settings > Linked Devices).
• No Messages Loading: It may take several minutes for history to load after initial authentication.

Sync Issues

If WhatsApp messages are out of sync with the bridge, delete the local database files and restart the bridge to re-authenticate:

• whatsapp-bridge/store/messages.db
• whatsapp-bridge/store/whatsapp.db

The MessageStore type provides a SQLite-backed mechanism for persisting WhatsApp chats and messages. It handles the creation of the store/messages.db database and the necessary schema for chats and messages tables.

Key capabilities:

• Store Chats: Persist chat metadata including JID, name, and last message timestamp.
• Store Messages: Save individual messages with support for text content and media metadata (URLs, keys, SHA256 hashes, etc.).
• Retrieve Messages: Fetch a list of Message objects from a specific chat, ordered by timestamp.
• Retrieve Chats: Get a map of all known chat JIDs and their last message timestamps.

The downloadMedia function retrieves media files associated with a specific message and saves them to a local directory structured by chat JID.

Workflow:

1. It looks up media metadata (URL, keys, SHA256, etc.) in the MessageStore using the messageID and chatJID.
2. It checks if the file already exists in store/<chat_jid_sanitized>/<filename> to avoid redundant downloads.
3. If not present, it uses the whatsmeow client to download the encrypted media.
4. It saves the decrypted file to the local filesystem.

Returns (bool, mediaType, filename, absPath, error).

The sendWhatsAppMessage function allows sending text or media messages to a recipient.

Recipient Formats:

• JID: A full WhatsApp JID (e.g., 123456789@s.whatsapp.net).
• Phone Number: A raw phone number string (e.g., 123456789), which the function automatically converts to a personal chat JID (user@s.whatsapp.net).

Media Types Supported:

• Images: .jpg, .jpeg, .png, .webp
• Audio: .ogg (Opus)
• Video: .mp4, .avi, .mov
• Documents: Any other file extension (defaults to application/octet-stream).

Returns (bool, string) indicating success status and a descriptive message.

The bridge exposes a REST API on port 8080 (by default) to interact with WhatsApp.

POST /api/send

Sends a message or media.

Request Body (SendMessageRequest):

• recipient (string, required): The JID or phone number.
• message (string, required): The text content.
• media_path (string, optional): Local filesystem path to the media file.

Response (SendMessageResponse):

• success (bool)
• message (string)

POST /api/download

Downloads media for a specific message.

Request Body (DownloadMediaRequest):

• message_id (string, required): The ID of the message containing media.
• chat_jid (string, required): The JID of the chat.

Response (DownloadMediaResponse):

• success (bool)
• message (string)
• filename (string, optional)
• path (string, optional): The absolute path to the downloaded file.