# webdriverio/mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/webdriverio/mcp  
**GitHub Stars:** 43  
**npm Downloads (last month):** 14422  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/webdriverio-mcp

## Description
Browser and mobile app automation using WebdriverIO, enabling AI agents to control browsers, interact with web elements, and automate native Android and iOS apps via the WebDriver and Appium protocols.

## Tools
Capabilities this server exposes over MCP:

- **enable_tools** — Add a group of tools: `mocks`, `cookies`, `device`, `extensions`, `attach`, `elements`, `cloud-apps
- **start_session** — Start a browser, local Electron application, or mobile app session; `attach: true` retains the existing Chrome CDP connection mode
- **attach_session** — Attach to an existing remote WebDriver/Appium session by ID without creating a new session
- **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 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. In browsers the result shows the new page's interactive elements with refs
- **snapshot** — The page as an accessibility tree with refs (`button "Save" [ref=e3]`), interactive elements by default (plain text is dropped, `full: true` shows it); pass refs to `perform_actions` for several steps; `find` returns only the parts containing a text (link targets included), `full: true` adds all te…
- **get_elements** — Get visible, interactable elements with bounds. Supports `inViewportOnly` (default: true) and `includeContainers` (default: false). Mobile and Electron; listed after `enable_tools({ groups: ['elements'] })`, use `snapshot` first
- **get_accessibility_tree** — Get the accessibility tree with roles, names, and selectors. Electron-only; browsers use `snapshot
- **get_screenshot** — Take a screenshot of the current page or screen (base64-encoded, auto-resized to max 2000px / 1MB)
- **get_tabs** — List all open browser tabs with handle, title, URL, and active status. Browser-only.
- **scroll** — Scroll in a direction (up/down) by specified pixels. Browser-only.
- **execute_script** — Execute arbitrary JavaScript in the browser, or Appium mobile commands on devices
- **execute_electron_script** — Execute privileged JavaScript in the Electron main process (Electron sessions only)
- **trigger_electron_deeplink** — Trigger an Electron deeplink whose scheme was explicitly configured at session start
- **mock** — Configure a session-scoped mock: an Electron main-process API function or a browser network request
- **get_mock_calls** — Inspect call arguments (Electron) or intercepted request records (browser) for a session-scoped mock
- **manage_mock** — Clear, reset, or restore a session-scoped mock
- **switch_tab** — Switch to a different browser tab by handle or 0-based index. Browser-only.
- **switch_frame** — Switch into an iframe by CSS/XPath selector, or back to the top-level frame if no selector is given. Browser-only.
- **click_element** — Click an element
- **set_value** — Replace the text of an input or textarea
- **select_option** — Select an option of a `<select>` by its text; for several steps use `perform_actions`. Browser-only.
- **press_key** — Press a key or combination (`Enter`, `Control+a`) in the focused element, optionally `times` (1-100) to repeat it; for several steps use `perform_actions`. Browser-only.
- **perform_actions** — Run several clicks, fills, selects, checks and key presses (`press` accepts `times` to repeat) in one call; stops at the first failure, when a step loads a new page, or before a key press that follows a click, select, check or uncheck that changed the page. Works for apps too (select, check and unc…
- **get_cookies** — Get all cookies for the current session, or a single cookie by name
- **set_cookie** — Set a cookie with name, value, and optional attributes
- **delete_cookies** — Delete all cookies or a specific cookie
- **tap_element** — Tap an element by selector or coordinates
- **swipe** — Swipe in a direction (up/down/left/right)
- **drag_and_drop** — Drag from one location to another
- **get_contexts** — List available automation contexts (NATIVE_APP, WEBVIEW_*) and the currently active one
- **switch_context** — Switch between native and webview contexts
- **get_app_state** — Get the current lifecycle state of a mobile app (not installed / not running / background / foreground)
- **rotate_device** — Rotate to portrait or landscape
- **hide_keyboard** — Hide on-screen keyboard
- **set_geolocation** — Set device GPS location
- **query_docs** — Search the official WebdriverIO documentation and return the most relevant excerpts with page, section and source URL. `query` is required (2-3 distinctive keywords — a sentence dilutes the ranking); `limit` defaults to 5 (max 20); `fullPage` (default: false) returns the full matched pages instead…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## 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`:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/webdriverio-mcp/readme_