How to add WebDriverIO MCP Server to Windsurf

Drive Chrome, Firefox, Edge, Safari and iOS/Android apps with WebDriverIO, locally or on cloud devices. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 31★ · stdio · no auth

Windsurf config for WebDriverIO MCP Server

npx -y @wdio/mcp@latest

{
  "mcpServers": {
    "webdriverio-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@wdio/mcp@latest"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the WebDriverIO MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5WebDriverIO MCP Server's tools become available to Cascade.

Before you start

Node.js with npx (the server runs via `npx -y @wdio/mcp@latest`)
A supported browser installed for web automation (Chrome, Firefox, Edge, or Safari; Safari requires macOS)
For mobile automation: Appium server (`npm install -g appium`) plus platform drivers (xcuitest for iOS, uiautomator2 for Android) and a running emulator/simulator or connected device
iOS automation requires macOS with Xcode; Android requires Android Studio
Optional cloud testing requires provider credentials (BrowserStack, Sauce Labs, LambdaTest, TestingBot, or Digital.ai)

What WebDriverIO MCP Server can do in Windsurf

start_session

Start a browser or app session. Use platform: 'browser' for web, platform: 'ios'/'android' for mobile, or attach: true to connect to a running Chrome instance.

launch_chrome

Launch a new Chrome instance with remote debugging enabled, for use with start_session({ attach: true }).

close_session

Close or detach from the current session (supports detach: true to disconnect without terminating).

emulate_device

Emulate a mobile/tablet device preset (viewport, DPR, UA, touch); requires a BiDi session.

open_web_extension

Install a web extension through WebDriver BiDi and open one of its extension pages so normal page tools can drive its UI.

navigate

Navigate to a URL.

get_elements

Get visible, interactable elements on the page. Supports inViewportOnly (default true) and includeContainers (default false) to include layout containers on mobile.

get_accessibility_tree

Get the page accessibility tree with roles, names, and selectors. Supports filtering by role and pagination. Browser-only.

Security

Cloud-provider testing requires provider credentials (e.g. BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY, SAUCE_USERNAME / SAUCE_ACCESS_KEY) set as environment variables or in the MCP client config. The server can execute arbitrary JavaScript via execute_script and drive browsers/devices, so run it only against targets you trust. HTTP transport mode includes DNS-rebinding protection via --allowedHosts and blocks browser clients unless --allowedOrigins is set.

WebDriverIO MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the WebDriverIO MCP Server config there under the "mcpServers" key and restart the client.

Is WebDriverIO MCP Server safe to use with Windsurf?

Do I need cloud credentials to use it?

No. Local browser and mobile automation work without any credentials. Provider credentials (e.g. BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY) are only needed when running tests on cloud real devices via BrowserStack, Sauce Labs, LambdaTest, TestingBot or Digital.ai.

What's required for mobile app automation?

An Appium server (`npm install -g appium`) plus the platform driver (xcuitest for iOS, uiautomator2 for Android), and a running emulator/simulator or connected device. iOS requires macOS with Xcode; Android requires Android Studio. Start the Appium server before launching mobile sessions.

Can it run without launching a subprocess?

Yes. By default it uses stdio (subprocess) transport, but for clients that cannot spawn subprocesses you can enable HTTP transport with `npx @wdio/mcp --http --port 3000` and point the client at http://localhost:3000/mcp.

View repo Full WebDriverIO MCP Server page