windsurf-search-mcp

MCP server and CLI for Windsurf/Devin server-side web search (GetWebSearchResults).

Zero runtime dependencies. Node.js >= 20.

This talks to Windsurf/Devin cloud endpoints with a personal session token. Use at your own risk; tokens expire and may violate the provider's terms if used outside the official client.

Install

npm i -g windsurf-search-mcp
# or without install:
npx -y -p windsurf-search-mcp windsurf-search --help

Auth (no secrets in config files)

Resolve order:

1. --api-key <token>
2. WINDSURF_API_KEY (or legacy WINDSURFAPI_CODEIUM_API_KEY)
3. first existing key file:
   • ~/.config/windsurf-search/api-key
   • ~/.windsurf-search/api-key
   • ~/.piwin/windsurf-api-key (compat)

Expected token shape: devin-session-token$...

# interactive (masked)
windsurf-search config set

# or non-interactive
windsurf-search config set 'devin-session-token$...'

windsurf-search config show
windsurf-search config test

Email/password login is also available (windsurf-search --login), but many accounts are OAuth-only and will reject password login.

CLI

windsurf-search "tauri window drag region" --limit 5
# stdout JSON:
# { "hits": [ { "title", "url", "snippet", "source": "windsurf" } ] }

Useful for agent hosts that spawn a custom CLI search source and parse JSON hits.

MCP server

Cursor / Claude Desktop / generic MCP host

{
  "mcpServers": {
    "windsurf-search": {
      "command": "npx",
      "args": ["-y", "windsurf-search-mcp"],
      "env": {
        "WINDSURF_API_KEY": "devin-session-token$..."
      }
    }
  }
}

Prefer putting the token in a key file and omitting env entirely:

{
  "mcpServers": {
    "windsurf-search": {
      "command": "npx",
      "args": ["-y", "windsurf-search-mcp"]
    }
  }
}

Then:

windsurf-search config set

Exposed tool

web_search

| arg | type | required | notes | |-----|------|----------|-------| | query | string | yes | search query | | limit | number | no | 1–10, default 5 | | domain | string | no | optional domain filter | | mode | number | no | optional upstream mode |

Returns MCP text content with JSON:

{ "hits": [ { "title": "...", "url": "...", "snippet": "...", "source": "windsurf" } ] }

Development

node --test test/*.mjs          # offline unit + protocol tests
RUN_LIVE_SEARCH=1 npm test      # also hit live API if key is configured

Security notes

• Never commit real tokens.
• Session tokens expire; re-run config set when searches return 401.
• config show only prints a masked key.
• This is not an official Windsurf/Devin product.

License

MIT