Webdriverio MCP

What webdriverio/mcp does

webdriverio/mcp exposes WebdriverIO automation through the Model Context Protocol. It can control Chrome, Firefox, Edge, Safari, local Electron applications, and native Android or iOS apps. Agents can start a new session, attach to an existing WebDriver or Appium session, or launch Chrome with remote debugging for an attachable session.

The server is suited to interactive browser automation, UI exploration, cross-platform application checks, and agent-driven test flows. It can also connect sessions to supported cloud testing providers: BrowserStack, Sauce Labs, LambdaTest, TestingBot, and Digital.ai Testing.

How it works

The default transport is stdio, allowing an MCP client to launch the server as a subprocess. HTTP transport is available for clients that cannot start subprocesses; the server listens on a configurable port and exposes MCP at /mcp. Host and origin controls are available for DNS rebinding protection and CORS configuration.

A typical flow starts with start_session, followed by navigate or application-specific actions. snapshot returns an accessibility-oriented view with references that can be passed to interaction tools. Sessions may also be attached to an existing remote WebDriver or Appium connection, and closed or detached when work is complete.

Mobile automation uses Appium. iOS requires the XCUITest driver and Xcode on macOS, while Android uses the UiAutomator2 driver and Android Studio. An emulator or physical device must be available, and the Appium server should be running before mobile actions begin.

Setup and configuration

The standard installation runs the latest package through npx:

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

The package can also be installed globally with npm install -g @wdio/mcp, then started with the wdio-mcp command. After changing client configuration, restart the MCP client.

For HTTP mode, run npx @wdio/mcp --http --port 3000. The default port is 3000, allowed hosts default to localhost addresses, and browser origins are blocked unless explicitly allowed.

Cloud sessions require credentials in environment variables or MCP client configuration. BrowserStack uses BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY; Sauce Labs uses SAUCE_USERNAME and SAUCE_ACCESS_KEY; LambdaTest uses TESTMU_USERNAME and TESTMU_ACCESS_KEY; and TestingBot uses TESTINGBOT_KEY and TESTINGBOT_SECRET.

Tools and capabilities

• Start, attach, close, or detach browser, Electron, and mobile sessions.
• Navigate pages, list and switch browser tabs, and switch into or out of iframes.
• Inspect accessibility snapshots, visible interactable elements, screenshots, and Electron accessibility trees.
• Click, fill, select, press keys, scroll, and batch multiple actions with perform_actions.
• Execute browser JavaScript, Appium mobile commands, or privileged Electron main-process scripts.
• Set, retrieve, and delete cookies.
• Emulate mobile and tablet presets in BiDi sessions, including viewport, device pixel ratio, user agent, and touch behavior.
• Install and drive web extensions, trigger configured Electron deeplinks, and configure session-scoped browser or Electron mocks.

Tool groups such as mocks, cookies, device, extensions, attach, elements, and cloud-apps can be enabled as needed.

Limitations and notes

Some capabilities are platform-specific. Tabs and scrolling are browser-only; Electron accessibility trees require Electron sessions; and device emulation requires a BiDi session. Element discovery through get_elements is available for mobile and Electron sessions after the elements tool group is enabled, while browser interaction is commonly driven through snapshot references.

Screenshots are returned as base64 data and automatically resized to a maximum of 2000 pixels or 1 MB. Session mocks are scoped to the session and can be inspected, cleared, reset, or restored.