WhatsApp MCP Server

A Model Context Protocol (MCP) server for WhatsApp, enabling Claude to read and send WhatsApp messages.

Originally created by Luke Harries. Maintained by Very Good Plugins.

Features

• Message Management: Search and read personal WhatsApp messages (text, images, videos, documents, audio)
• Contact Search: Search contacts by name or phone number with sender_display format ("Name (phone)")
• Send Messages: Send text messages to individuals or groups
• Media Support: Send and download images, videos, documents, and voice messages
• Call History: Capture incoming voice/video calls into a local SQLite table (live, 1:1 and group)
• Webhook Integration: Forward incoming messages to external services
• Local Storage: All messages stored locally in SQLite - only sent to Claude when you allow it

Installation

Prerequisites

• Go 1.25+
• Python 3.11+
• uv package manager
• Claude Desktop or Cursor
• FFmpeg (optional, for voice message conversion)

Quick Start

1. Clone the repository

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

2. Start the WhatsApp bridge

   cd whatsapp-bridge
   go run .
   

   On first start, the bridge prints and stores a local REST API token at whatsapp-bridge/store/.bridge-token. Scan the QR code with WhatsApp on your phone to authenticate.

3. Configure Claude Desktop

   Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

   Replace /path/to/whatsapp-mcp with your actual path.

4. Restart Claude Desktop

Updating

Pull the latest changes, then refresh whichever components moved:

git pull

Updates do not require re-pairing or deleting whatsapp.db — your session and message history are preserved. Re-pairing is only needed when explicitly requesting full history (see Requesting full history).

For v0.2.1 and later, restart both the bridge and MCP server after updating so the MCP server can read the bridge token. If the two components do not share the same checkout, set the same WHATSAPP_BRIDGE_TOKEN value in both environments.

Cursor IDE Configuration

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcp": {
    "servers": {
      "whatsapp": {
        "command": "uv",
        "args": [
          "--directory",
          "/path/to/whatsapp-mcp/whatsapp-mcp-server",
          "run",
          "main.py"
        ]
      }
    }
  }
}

Tools

Messages include sender_display showing "Name (phone)" format for easy identification by agents.

Contact Operations

search_contacts

Search contacts by name or phone number.

Parameters:

• query (required): Name or phone number to search

Natural Language Examples:

• "Find contacts named John"
• "Search for phone number 555-1234"
• "Who has the phone number starting with +1?"

get_contact

Resolve a WhatsApp contact name from a phone number, LID, or full JID.

Parameters:

• identifier (required): Phone number, LID, or full JID (aliases: phone_number, phone)
  • Examples: 12025551234, 184125298348272, 12025551234@s.whatsapp.net, 184125298348272@lid

Natural Language Examples:

• "What's the name for phone number 5551234567?"
• "Look up who owns this number"
• "Who is 184125298348272@lid?"

Message Operations

list_messages

Get messages with filters, date ranges, and sorting.

Parameters:

• chat_jid (optional): Filter by specific chat JID
• limit (optional): Number of messages (default 50, max 500)
• before_date (optional): Messages before this date (YYYY-MM-DD)
• after_date (optional): Messages after this date (YYYY-MM-DD)
• sort_by (optional): "newest" or "oldest" (default "newest")

Natural Language Examples:

• "Show me the last 100 messages from today"
• "Get messages from the family group chat"
• "Find messages from last week"

send_message

Send a text message to a contact or group, optionally as a quoted reply.

Parameters:

• recipient (required): Phone number or group JID
• message (required): Text content to send
• quoted_message_id (optional): ID of the message to reply to. When provided, the sent message appears as a quoted reply in WhatsApp.
• quoted_sender_jid (optional): Full JID of the author of the quoted message. Required for group replies so WhatsApp renders the correct attribution header.
• quoted_content (optional): Text content of the quoted message, used for the reply preview. Only plain text is supported.

Inbound quoted replies are stored automatically. The quoted_message_id field in each message returned by list_messages indicates which message it is replying to (or null for non-replies).

Natural Language Examples:

• "Send 'Hello!' to +1234567890"
• "Message the team group saying 'Meeting at 3pm'"
• "Reply to that message saying 'Sounds good'"

send_reaction

Send (or remove) an emoji reaction to a message.

Parameters:

• recipient (required): Chat JID the message belongs to (phone JID or group JID)
• message_id (required): ID of the message to react to
• emoji (required): Reaction emoji (e.g. "👍"). Pass an empty string "" to remove an existing reaction.
• from_me (optional, default false): Whether the original message was sent by the current user
• sender_jid (optional): Full JID of the original message sender — required for group messages when from_me is false so the correct WhatsApp key is built

Inbound reactions received from others are stored automatically as messages with media_type = "reaction". The reaction_to_message_id field in each reaction message indicates which message was reacted to.

When webhook forwarding is enabled, inbound reactions are also posted to WEBHOOK_URL as typed events. Reaction removals use an empty content/reactionEmoji and reactionRemoved: true.

{
  "eventType": "reaction",
  "sender": "15551234567",
  "chatJID": "15551234567@s.whatsapp.net",
  "isFromMe": true,
  "content": "👍",
  "messageId": "reaction-stanza-id",
  "mediaType": "reaction",
  "reactionToMessageId": "target-message-id",
  "reactionEmoji": "👍",
  "reactionRemoved": false
}

Natural Language Examples:

• "React to that message with a thumbs up"
• "Remove my reaction from the last message in the group chat"

send_file

Send a media file (image, video, document).

Parameters:

• recipient (required): Phone number or group JID
• file_path (required): Path to the file
• caption (optional): Caption for the media

The bridge only reads files inside configured media roots. By default this is ~/.local/share/whatsapp-mcp/outbox; set WHATSAPP_MEDIA_ROOTS to allow additional absolute directories.

send_audio_message

Send a voice message (automatically converts to Opus .ogg format).

Parameters:

• recipient (required): Phone number or group JID
• file_path (required): Path to audio file

Converted audio is sent through the same media-path confinement as send_file.

download_media

Download media from a received message.

Parameters:

• message_id (required): ID of the message with media
• chat_jid (required): JID of the chat containing the message

Chat Operations

list_chats

List all chats with metadata.

Parameters:

• limit (optional): Number of chats (default 50, max 200)

get_chat

Get specific chat metadata by JID.

Parameters:

• jid (required): Chat JID

get_direct_chat_by_contact

Find a direct message chat with a contact.

Parameters:

• phone (required): Phone numb