Browser Use MCP Server for Windsurf: Setup & Config

What you can do with Browser Use in Windsurf

A browser-use bridge with live viewing and both asynchronous and completion-wait browsing workflows.

• Watch an automated browsing session through VNC.
• Connect a stdio-only client through the documented proxy workflow.

Before you start: Browser Use in Windsurf

• Python and uv
• Playwright and its Chromium browser dependencies
• mcp-proxy for stdio mode
• A built and globally installed browser-use-mcp-server package

The README installs mcp-proxy with uv, synchronizes dependencies, installs Chromium through Playwright, builds a wheel, and installs it globally before this launch. Its source SSE alternative uses uv run server --port 8000 and http://localhost:8000/sse. CHROME_PATH and PATIENT are optional settings.

Browser Use Windsurf configuration

1. Choose Windsurf configuration scope

   For Browser Use 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 Browser Use MCP Server to Windsurf

   Use the browser-use-mcp-server entry below in mcpServers. Keep Browser Use MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Browser Use MCP Server in Windsurf

   Browser Use MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "browser-use-mcp-server",
      "args": [
        "run",
        "server",
        "--port",
        "8000",
        "--stdio",
        "--proxy-port",
        "9000"
      ],
      "env": {
        "OPENAI_API_KEY": "<OpenAI API key>"
      }
    }
  }
}

Troubleshooting Browser Use in Windsurf

• Check browser-use-mcp-server on the machine running Windsurf's MCP integration for Browser Use MCP Server; refresh MCP and inspect Cascade's tools.
• Check OPENAI_API_KEY for Browser Use MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Browser Use MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Stdio mode requires mcp-proxy and package build/install steps.
• Known limitation: Requires Playwright browser setup and an OpenAI API key.
• Known limitation: Docker's documented VNC default should be replaced for protected viewing.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions