Playwright MCP server in Windsurf.
Cascade writes the code; playwright-mcp lets it check the result in a real browser. Setup is one block in mcp_config.json and a refresh.
Cascade, Windsurf's agent, gets noticeably more useful on frontend work when it can see what it shipped. playwright-mcp — Microsoft's browser-automation MCP server, 33.7k stars — adds tools for navigating, clicking, filling, and snapshotting pages, with the accessibility tree as the interface so the agent targets real elements rather than screen regions.
Windsurf keeps all MCP servers in one global JSON file, so this is a two-minute job: add the block, refresh Cascade's server list, done.
Where Windsurf keeps MCP config
Everything lives in ~/.codeium/windsurf/mcp_config.json. There's no per-project MCP file — a server added here is available in every workspace, which suits a general-purpose tool like a browser. The UI path to the same place is Windsurf Settings > Cascade > MCP Servers > Add Server.
Node 18+ is the only prerequisite; Windsurf will start the server through npx, downloading the @playwright/mcp package on first launch. If you'd rather pin a version than track latest, replace @latest with an exact one — useful when a team wants identical tool behavior across machines.
Add the server block
Insert the playwright entry under mcpServers (merge with existing entries if the file isn't empty):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}Refresh, verify, and first run
Manual edits to mcp_config.json aren't hot-reloaded — go to Settings > Cascade > MCP Servers and hit refresh, or restart Windsurf. The playwright server should list with its tools: browser_navigate, browser_click, browser_snapshot, browser_take_screenshot, and more.
Hand Cascade a check it can't fake: "open localhost:3000/login, submit the form empty, and tell me what validation errors appear." A Chromium window opens and you can watch the run; append "--headless" to args once the novelty wears off and you'd rather it work out of sight.
Troubleshooting in Windsurf
Not in the list after refresh: the file didn't parse. A trailing comma or a second mcpServers object (instead of merging entries into one) makes Windsurf skip the config without complaint — lint the JSON.
Listed but failing to start: PATH, almost certainly. Windsurf launched from the Dock or Start menu doesn't get your shell's PATH additions, and nvm-managed Node is a frequent casualty. Use the absolute path to npx as command, or launch Windsurf from a terminal.
Tools error on first real call: Playwright may lack a browser binary on this machine. One-time fix in any terminal: npx playwright install chromium, then refresh the server.
Cascade has the tools but won't use them: be explicit in the prompt ('use the browser to...') the first few times; once a workspace has a history of browser-verified tasks, Cascade reaches for the tools on its own.
Find it on the index
The live listing for playwright-mcp — package, category, and probed tool inventory — is at https://loomal.ai/marketplace/playwright-mcp. It's part of Loomal's Browser Automation category, a useful page when you want to weigh it against alternatives like Chrome DevTools MCP before standardizing your setup.
FAQ
How do I install Playwright MCP in Windsurf?
Add a playwright entry (command npx, args ["@playwright/mcp@latest"]) under mcpServers in ~/.codeium/windsurf/mcp_config.json — or use Settings > Cascade > MCP Servers > Add Server — then refresh the MCP server list. Cascade picks up the browser tools immediately after the server connects.
Does Windsurf support per-project MCP servers?
No — mcp_config.json is global, so playwright-mcp will be available in every workspace once added. If you only want browser automation sometimes, you can remove or comment out the entry and refresh, but there's no workspace-level toggle.
Why does the server fail to start when npx works in my terminal?
GUI-launched Windsurf inherits a minimal PATH that often misses version-manager Node installs. Either set the command field to the absolute path of npx (run which npx to find it) or launch Windsurf from the terminal session where Node resolves.
Headed or headless in Windsurf?
Start headed — watching Cascade drive the browser is the fastest way to spot where its element targeting goes wrong. Switch to headless by adding "--headless" to args once browser verification becomes a background step in your workflow rather than something you supervise.
Browse more MCP servers for Windsurf.
The Loomal index lists tools, packages, and per-call pricing.