WhatsApp MCP Server for Claude Code: Setup & Config

What you can do with WhatsApp in Claude Code

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

• Find a past message and inspect its surrounding conversation.
• Download received media or send a playable voice message.

Before you start: WhatsApp in Claude Code

• 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 Code configuration

1. Choose Claude Code configuration scope

   For WhatsApp MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add WhatsApp MCP Server to Claude Code

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

3. Check WhatsApp MCP Server in Claude Code

   WhatsApp MCP Server: Inspect claude mcp list and /mcp status.

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

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

WhatsApp tools available to Claude Code

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

search_contacts

For WhatsApp's search_contacts, review the permission request and arguments in Claude Code before approval.

Find WhatsApp contacts using a name or phone number.

list_messages

For WhatsApp's list_messages, review the permission request and arguments in Claude Code before approval.

Retrieve messages using filters and optional contextual information.

list_chats

For WhatsApp's list_chats, review the permission request and arguments in Claude Code before approval.

Enumerate chats along with their metadata.

get_chat

For WhatsApp's get_chat, review the permission request and arguments in Claude Code before approval.

get_direct_chat_by_contact

For WhatsApp's get_direct_chat_by_contact, review the permission request and arguments in Claude Code before approval.

get_contact_chats

For WhatsApp's get_contact_chats, review the permission request and arguments in Claude Code before approval.

get_last_interaction

For WhatsApp's get_last_interaction, review the permission request and arguments in Claude Code before approval.

get_message_context

For WhatsApp's get_message_context, review the permission request and arguments in Claude Code before approval.

send_message

For WhatsApp's send_message, review the permission request and arguments in Claude Code before approval.

send_file

For WhatsApp's send_file, review the permission request and arguments in Claude Code before approval.

Send a supported image, video, document, or raw audio file.

send_audio_message

For WhatsApp's send_audio_message, review the permission request and arguments in Claude Code before approval.

Send playable voice audio using Opus input or FFmpeg conversion.

download_media

For WhatsApp's download_media, review the permission request and arguments in Claude Code before approval.

Fetch a message attachment and return its local path.

WhatsApp: full stored tool descriptions

Troubleshooting WhatsApp in Claude Code

• 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 Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions