Playwright MCP for Windsurf: Setup & Config

What you can do with Playwright in Windsurf

Choose structured browser interaction with persistent state and detailed inspection tools.

• Fill forms and exercise interactive browser flows.
• Keep browser state across a long-running agent workflow.

Before you start: Playwright in Windsurf

• Node.js 18 or later
• An MCP-compatible client

Add the command to your client's MCP configuration. Browser selection, headless operation, and connection settings are configurable through documented arguments.

Playwright Windsurf configuration

1. Choose Windsurf configuration scope

   For Playwright 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 Playwright MCP to Windsurf

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

3. Check Playwright MCP in Windsurf

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

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

Playwright tools available to Windsurf

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

browser_close

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_close.

Shut the active page.

browser_resize

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_resize.

Change the browser window dimensions.

browser_console_messages

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_console_messages.

browser_handle_dialog

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_handle_dialog.

browser_emulate_media

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_emulate_media.

browser_evaluate

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_evaluate.

browser_file_upload

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_file_upload.

browser_drop

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_drop.

browser_find

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_find.

Find text or regex matches within the page accessibility snapshot.

browser_fill_form

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_fill_form.

Populate several form fields together.

browser_press_key

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_press_key.

Send a keyboard key press.

browser_type

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_type.

Enter text in an editable page element.

browser_navigate

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_navigate.

Open a specified web address.

browser_navigate_back

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_navigate_back.

browser_network_requests

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_network_requests.

browser_network_request

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_network_request.

browser_run_code_unsafe

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_run_code_unsafe.

browser_take_screenshot

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_take_screenshot.

browser_snapshot

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_snapshot.

browser_click

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_click.

Click a page element.

browser_drag

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_drag.

Drag from one page element to another.

browser_hover

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_hover.

Position the pointer over an element.

browser_select_option

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_select_option.

Choose an entry from a dropdown control.

browser_tabs

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_tabs.

Inspect, open, switch, or close tabs.

browser_wait_for

After refreshing Playwright in Windsurf settings, check Cascade's tool list for browser_wait_for.

Pause for matching text, its disappearance, or an elapsed interval.

Playwright: full stored tool descriptions

Troubleshooting Playwright in Windsurf

• Check npx @playwright/mcp@latest (Node.js/npm) on the machine running Windsurf's MCP integration for Playwright MCP; refresh MCP and inspect Cascade's tools.
• Playwright MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires Node.js 18 or later.
• Known limitation: Tool schemas and accessibility trees can use more context than the separate CLI workflow.
• Known limitation: Origin filters are not a security boundary.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions