WhatsApp MCP Server for Claude Desktop: Setup & Config

What you can do with WhatsApp in Claude Desktop

Choose local WhatsApp history search with contact context and text, file, and voice-message tools.

• Find a past message and inspect its surrounding conversation.
• Locate contacts and their direct chats.

Before you start: WhatsApp in Claude Desktop

• Go
• Python 3.6+
• uv
• Claude Desktop or Cursor
• A personal WhatsApp account and mobile app

Replace the README path placeholders with your uv executable and cloned source location. First run go run main.go in whatsapp-bridge and authenticate by QR code. FFmpeg is optional for voice conversion; Windows needs CGO and a C compiler.

WhatsApp Claude Desktop configuration

1. Choose Claude Desktop configuration scope

   For WhatsApp MCP Server, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

2. Add WhatsApp MCP Server to Claude Desktop

   Use the whatsapp-mcp entry below in mcpServers. Keep WhatsApp MCP Server's documented stdio connection fields and your other Claude Desktop entries.

3. Check WhatsApp MCP Server in Claude Desktop

   WhatsApp MCP Server: Fully quit and reopen Claude Desktop; check developer diagnostics.

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

WhatsApp tools available to Claude Desktop

WhatsApp's stored tool list documents 12 tools; compare it with Claude Desktop's connected tool list, because the stored list is not a live check.

search_contacts

When Claude Desktop requests search_contacts from WhatsApp, review the action before approving it.

Find WhatsApp contacts using a name or phone number.

list_messages

When Claude Desktop requests list_messages from WhatsApp, review the action before approving it.

Retrieve messages using filters and optional contextual information.

list_chats

When Claude Desktop requests list_chats from WhatsApp, review the action before approving it.

Enumerate chats along with their metadata.

get_chat

When Claude Desktop requests get_chat from WhatsApp, review the action before approving it.

Inspect one chat's information.

get_direct_chat_by_contact

When Claude Desktop requests get_direct_chat_by_contact from WhatsApp, review the action before approving it.

Locate a one-to-one conversation for a contact.

get_contact_chats

When Claude Desktop requests get_contact_chats from WhatsApp, review the action before approving it.

Find conversations in which a contact participates.

get_last_interaction

When Claude Desktop requests get_last_interaction from WhatsApp, review the action before approving it.

get_message_context

When Claude Desktop requests get_message_context from WhatsApp, review the action before approving it.

send_message

When Claude Desktop requests send_message from WhatsApp, review the action before approving it.

send_file

When Claude Desktop requests send_file from WhatsApp, review the action before approving it.

send_audio_message

When Claude Desktop requests send_audio_message from WhatsApp, review the action before approving it.

download_media

When Claude Desktop requests download_media from WhatsApp, review the action before approving it.

WhatsApp: full stored tool descriptions

Troubleshooting WhatsApp in Claude Desktop

• Known limitation: Requires both the Go bridge and Python server to run.
• Known limitation: QR authentication can need renewal; initial history loading may take time.
• Known limitation: Private chat content can create prompt-injection and data-exposure risks.
• General Claude Desktop troubleshooting lives in the /clients/claude-desktop guide.

Frequently asked questions