WhatsApp Bridge MCP server

This MCP server allows you to integrate your personal WhatsApp account with Claude AI. It enables searching and reading messages (including media), managing contacts, and sending various types of messages. Your data is stored locally in a SQLite database and only shared with an LLM when explicitly accessed through tools you control.

Installation Requirements

Prerequisites

• Go
• Python 3.6+
• Anthropic Claude Desktop app (or Cursor)
• UV (Python package manager)
• FFmpeg (optional) - Only needed for audio message conversion

Installation Process

1. Clone the repository

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

2. Start the WhatsApp bridge

   cd whatsapp-bridge
   go run main.go
   

   On first run, scan the displayed QR code with your WhatsApp mobile app to authenticate. You may need to re-authenticate approximately every 20 days.

3. Configure your AI application

   Create a configuration file with the following JSON (replace {{PATH}} placeholders with your actual paths):

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

   For Claude Desktop, save this as claude_desktop_config.json in:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   For Cursor, save this as mcp.json in:

   ~/.cursor/mcp.json
   

4. Restart your AI application

   After restarting Claude Desktop or Cursor, WhatsApp should appear as an available integration.

Windows Setup Instructions

Windows users need to enable CGO for the SQLite integration:

1. Install a C compiler
   Install MSYS2 and add the ucrt64\bin folder to your PATH.

2. Enable CGO and run the application

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

Using the WhatsApp MCP

Once connected, you can interact with your WhatsApp through Claude using the following tools:

Contact Management

• search_contacts: Find contacts by name or number
• list_chats: View available chats with metadata
• get_chat: Get details about a specific chat
• get_direct_chat_by_contact: Find a direct chat with a contact
• get_contact_chats: List all chats involving a specific contact

Message Handling

• list_messages: Retrieve messages with optional filters
• get_message_context: Get context around a specific message
• get_last_interaction: View most recent message with a contact

Sending Content

• send_message: Send a text message to a number or group
• send_file: Send media files (images, videos, documents)
• send_audio_message: Send voice messages (requires .ogg format or FFmpeg)

Media Management

• download_media: Download media from messages to your local system

Media Handling

The server supports various media operations:

Sending Media

• Use send_file for images, videos, and documents
• Use send_audio_message for voice messages
  • Audio should be in .ogg Opus format for best results
  • With FFmpeg installed, other audio formats will be converted automatically

Accessing Received Media

Media messages initially only store metadata in the database. To access the actual media:

1. Note the message_id and chat_jid from the message containing media
2. Use the download_media tool with these parameters
3. The tool will download the media and return a file path for access

Troubleshooting

Common Issues

• Permission problems: Ensure UV is in your PATH or use full path
• Both components required: Both Go bridge and Python server must be running

Authentication Problems

• QR code issues: Restart the bridge if the QR code doesn't appear
• Device limit: WhatsApp limits linked devices; remove unused ones from your phone
• Initial loading: Message history may take several minutes to load initially
• Synchronization issues: If messages get out of sync, delete the database files (whatsapp-bridge/store/messages.db and whatsapp-bridge/store/whatsapp.db) and restart

For more Claude Desktop integration help, visit the MCP documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect