BrowserTools MCP for Windsurf: Setup & Config

What you can do with BrowserTools in Windsurf

Browser evidence and Lighthouse audits in one MCP workflow, with an explicit inactive-project caveat.

• Capture screenshots and inspect a selected DOM element.
• Sequence auditing or debugging operations through dedicated modes.

Before you start: BrowserTools in Windsurf

• Chrome with the BrowserTools extension
• A compatible MCP client
• Node.js tooling
• A separate browser-tools-server process
• The BrowserToolsMCP DevTools panel open

Run npx @agentdeskai/browser-tools-server@latest separately. The MCP package belongs in the client configuration. The project is no longer active.

BrowserTools Windsurf configuration

1. Choose Windsurf configuration scope

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

2. Add BrowserTools MCP to Windsurf

   Use the browser-tools-mcp entry below in mcpServers. Keep BrowserTools MCP's documented stdio connection fields and your other Windsurf entries.

3. Check BrowserTools MCP in Windsurf

   BrowserTools MCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "browser-tools-mcp": {
      "command": "npx",
      "args": [
        "@agentdeskai/browser-tools-mcp@latest"
      ],
      "env": {}
    }
  }
}

BrowserTools tools available to Windsurf

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

runAccessibilityAudit

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runAccessibilityAudit.

Check the page for accessibility problems, including WCAG-related issues.

runPerformanceAudit

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runPerformanceAudit.

Inspect page loading and rendering performance.

runSEOAudit

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runSEOAudit.

runBestPracticesAudit

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runBestPracticesAudit.

Check the page against web development practices.

runAuditMode

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runAuditMode.

runNextJSAudit

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runNextJSAudit.

runDebuggerMode

After refreshing BrowserTools in Windsurf settings, check Cascade's tool list for runDebuggerMode.

Execute the debugging tools in their prescribed order.

BrowserTools: full stored tool descriptions

Troubleshooting BrowserTools in Windsurf

• Check npx @agentdeskai/browser-tools-mcp@latest (Node.js/npm) on the machine running Windsurf's MCP integration for BrowserTools MCP; refresh MCP and inspect Cascade's tools.
• BrowserTools MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: The project explicitly states that it is no longer active.
• Known limitation: Requires an extension and two distinct server components.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions