WhatsApp MCP Server for Cursor: Setup & Config

What you can do with WhatsApp in Cursor

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

• Send text or documents to an individual or group.
• Download received media or send a playable voice message.

Before you start: WhatsApp in Cursor

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

1. Choose Cursor configuration scope

   For WhatsApp MCP Server, open Project: .cursor/mcp.json User: ~/.cursor/mcp.json. Merge into mcpServers at project or user scope.

2. Add WhatsApp MCP Server to Cursor

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

3. Check WhatsApp MCP Server in Cursor

   WhatsApp MCP Server: Enable in Cursor’s MCP settings; inspect tools.

{
  "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 Cursor

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

search_contacts

Find search_contacts under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

list_messages

Find list_messages under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

list_chats

Find list_chats under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

get_chat

Find get_chat under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

get_direct_chat_by_contact

Find get_direct_chat_by_contact under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

get_contact_chats

Find get_contact_chats under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

get_last_interaction

Find get_last_interaction under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Retrieve the latest message exchanged with a contact.

get_message_context

Find get_message_context under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Read messages surrounding a selected message.

send_message

Find send_message under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Send text to a phone number or group JID.

send_file

Find send_file under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

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

send_audio_message

Find send_audio_message under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Send playable voice audio using Opus input or FFmpeg conversion.

download_media

Find download_media under WhatsApp in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Fetch a message attachment and return its local path.

WhatsApp: full stored tool descriptions

Troubleshooting WhatsApp in Cursor

• 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 Cursor troubleshooting lives in the /clients/cursor guide.

Frequently asked questions