WhatsApp MCP Server for Windsurf: Setup & Config

What you can do with WhatsApp in Windsurf

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

• Locate contacts and their direct chats.
• Download received media or send a playable voice message.

Before you start: WhatsApp in Windsurf

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

1. Choose Windsurf configuration scope

   For WhatsApp MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add WhatsApp MCP Server to Windsurf

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

3. Check WhatsApp MCP Server in Windsurf

   WhatsApp MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s 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 Windsurf

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

search_contacts

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for search_contacts.

list_messages

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for list_messages.

list_chats

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for list_chats.

get_chat

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for get_chat.

Inspect one chat's information.

get_direct_chat_by_contact

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for get_direct_chat_by_contact.

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

get_contact_chats

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for get_contact_chats.

Find conversations in which a contact participates.

get_last_interaction

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for get_last_interaction.

get_message_context

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for get_message_context.

send_message

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for send_message.

send_file

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for send_file.

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

send_audio_message

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for send_audio_message.

Send playable voice audio using Opus input or FFmpeg conversion.

download_media

After refreshing WhatsApp in Windsurf settings, check Cascade's tool list for download_media.

Fetch a message attachment and return its local path.

WhatsApp: full stored tool descriptions

Troubleshooting WhatsApp in Windsurf

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

Frequently asked questions