How to add WhatsApp MCP Server (lharries) to Windsurf

Connect your personal WhatsApp: search, read and send messages and media locally Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 5.7k★ · stdio · no auth

Windsurf config for WhatsApp MCP Server (lharries)

git clone https://github.com/lharries/whatsapp-mcp && cd whatsapp-mcp/whatsapp-bridge && go run main.go

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

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the WhatsApp MCP Server (lharries) config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5WhatsApp MCP Server (lharries)'s tools become available to Cascade.

Before you start

Go (to build and run the WhatsApp bridge)
Python 3.6+ and the uv package manager (for the MCP server)
Claude Desktop or Cursor as the MCP client
A phone with WhatsApp installed to scan the linking QR code (an available device-link slot)
FFmpeg (optional) — required only for sending audio as proper WhatsApp voice messages

What WhatsApp MCP Server (lharries) can do in Windsurf

search_contacts

Search your contacts by name or number

list_chats

List available chats with metadata

list_messages

Retrieve messages, with filters and context

get_chat

Get metadata about a specific chat

get_direct_chat_by_contact

Find a direct chat with a specific contact

get_contact_chats

List all chats involving a specific contact

get_last_interaction

Get the most recent message with a contact

get_message_context

Retrieve messages around a given message

Security

Authenticates against your personal WhatsApp via the unofficial web multidevice API (QR pairing), which can risk account flags and stores your full chat history in a local unencrypted SQLite DB — protect the data files and the host machine.

WhatsApp MCP Server (lharries) + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the WhatsApp MCP Server (lharries) config there under the "mcpServers" key and restart the client.

Is WhatsApp MCP Server (lharries) safe to use with Windsurf?

Does this use the WhatsApp Business API?

No. It links to your personal account via WhatsApp's web multidevice API (the same mechanism as WhatsApp Web), using the whatsmeow Go library — no Business API or paid cloud service.

Where are my messages stored?

Locally, in a SQLite database under whatsapp-bridge/store/. They're only sent to the LLM when a tool reads them.

Why do I have to re-link every few weeks?

WhatsApp's multidevice sessions expire roughly every 20 days, so you'll periodically re-scan the QR code to re-authenticate.

View repo Full WhatsApp MCP Server (lharries) page