WebdriverIO MCP

by webdriverio

315 downloads

Not rated

GitHub

About

A Model Context Protocol (MCP) server that enables AI assistants to interact with web browsers and mobile applications using WebDriverIO. Automate Chrome browsers, iOS apps, and Android apps—all through a unified interface.

Details

Author: webdriverio
Downloads: 315
Categories: Developer Tools, Automation, Other

- Start browser sessions in headed or headless modes
- Navigate URLs, click elements, fill forms, and take screenshots
- Manage cookies (get, set, delete)
- Attach to a running Chrome instance via remote debugging
- Emulate mobile devices (iPhone 15, Pixel 7) with BiDi sessions
- Record all tool calls as executable WebDriverIO JS
- Test native iOS/Android apps with gestures, app lifecycle, and context switching
- Switch between native and webview contexts for hybrid apps

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name WebdriverIO MCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Add the server configuration to your Claude Desktop MCP settings using either npx -y @wdio/mcp or a globally installed wdio-mcp binary. For mobile automation, install Appium globally and the required platform drivers (xcuitest for iOS, uiautomator2 for Android). Start an Appium server before using mobile features. Then launch Claude Desktop and interact with browsers or apps using the provided tools (e.g., start_browser, start_app_session, navigate, click_element).

`start_session`

Starts a new browser or mobile automation session. Only one active session at a time — starting another session closes or detaches from the existing session first. Use attach: true to connect to a running Chrome via CDP.

`attach_session`

Attaches to an existing remote WebDriver or Appium session by ID without creating a new session. Only one session can be active at a time. The externally managed session is detached, not terminated, by default on close.

`close_session`

Closes the current session or detaches without terminating. Detach preserves app state on the Appium server — sessions with noReset: true auto-detach by default. Closing a browser attach session terminates chromedriver but the Chrome process spawned by launch_chrome remains running.

`launch_chrome`

Launches Chrome with remote debugging enabled. Wipes and recreates a temporary profile directory on each call. Mode "newInstance" (default) runs alongside existing Chrome; "freshSession" starts with an empty profile. Set copyProfileFiles to copy cookies/logins from your Default profile — changes do not sync back. After launch, call start_session with attach: true to connect. Spawns a detached Chrome process that persists if the server exits.

`emulate_device`

Emulates a mobile or tablet device in the current browser session by setting viewport, DPR, user-agent, and touch events. Requires a BiDi-enabled session (start_session with capabilities: { webSocketUrl: true }). Omit device to list available presets. Pass "reset" to restore desktop defaults. Changes persist for all subsequent tool calls until reset or session close. Browser-only.

`navigate`

Loads a URL in the current tab and waits for the page load event. Resets page state — DOM, JS runtime, timers, and frame context are destroyed. Use instead of clicking links when the target URL is known.

`switch_tab`

Focuses a browser tab by window handle or 0-based index. All subsequent tool calls operate on the active tab. Provide handle OR index — use get_tabs to find them. Browser-only; use switch_context for mobile webviews.

`switch_frame`

Switches WebDriver frame context into an iframe by CSS/XPath selector, or back to top-level if selector is omitted. Changes persist — all subsequent click_element, set_value, get_elements calls operate within the switched frame until you switch back. Waits up to 5s for the iframe. Browser-only.

`scroll`

Scrolls the page vertically by a pixel amount. Browser-only — for mobile scrolling use swipe. Only supports up/down; no horizontal scrolling.

`click_element`

Waits for an element, scrolls it into view, and fires element.click(). May trigger navigation, form submission, or modals. Browser sessions only — on iOS element.click() is silently ignored; use tap_element instead. Default timeout: 3000ms.

`set_value`

Clears an input or textarea then types the given text character by character. Always replaces existing content — clearValue() runs first. Triggers input, change, and key events which may fire validation or autocomplete. Scrolls into view by default.

`set_cookie`

Sets a browser cookie on the active session. The browser must already be on the target domain — cookies cannot be set cross-domain. Use to inject session tokens or feature flags without login flows.

`delete_cookies`

Deletes all cookies or a single cookie by name from the current browser session. Irreversible — deleted cookies cannot be recovered.

`tap_element`

Taps a matched element via element.tap() or at absolute screen coordinates (x, y). No scroll-into-view or wait — element must already be visible on screen. Use instead of click_element on iOS where element.click() is ignored. Provide selector OR both x and y. Mobile-only.

`swipe`

Performs a full-screen swipe gesture. Direction is content movement — "up" scrolls content upward (finger moves down). For browser scrolling use scroll; for dragging a specific element use drag_and_drop. No error if content cannot scroll further. Mobile-only.

`drag_and_drop`

Drags an element to another element or to relative x/y offsets. x and y are offsets from the source element, not absolute screen coordinates (unlike tap_element). Provide targetSelector OR both x and y. Mobile-only.

`switch_context`

Switches between native and webview automation contexts in a hybrid mobile app. In NATIVE_APP context, use accessibility IDs; in WEBVIEW_* context, use CSS/XPath. Changes persist for all subsequent commands. Accepts context name or 1-based index. Use get_contexts to discover available targets. Mobile-only.

`rotate_device`

Rotates a mobile device to portrait or landscape orientation. Waits for the OS rotation animation to complete. Use to test orientation-dependent layouts. Mobile-only; no effect in browser sessions.

`hide_keyboard`

Dismisses the on-screen keyboard on mobile. Call after text entry when the keyboard obscures elements. No-op if already hidden. Mobile-only.

`set_geolocation`

Overrides GPS coordinates for the session. Affects navigator.geolocation in browsers and location services on mobile. Location permissions must already be granted to the app.

`execute_script`

Executes arbitrary JavaScript in browser page context or Appium mobile: commands. Can read/modify DOM, trigger events, terminate apps, or run Android shell commands — use only when no dedicated tool covers the action. Browser: pass JS in script, use 'return' for values, string args matching selectors auto-resolve to elements. Mobile: use 'mobile: <command>' syntax in script with args array (e.g. "mobile: pressKey", "mobile: activateApp"). Prefer click_element/set_value/get_elements for standard interactions.

`get_elements`

Returns interactable elements on the current page with selectors, text, and bounding boxes. Supports filtering by element type, viewport visibility, and pagination. Use when the wdio://session/current/elements resource does not return desired elements.

`open_web_extension`

Installs a web extension through WebDriver BiDi and opens one of its extension pages so existing MCP tools can inspect and drive its UI. Requires a BiDi-enabled browser session. Use base64 for cloud/remote sessions where the browser driver cannot read the MCP server filesystem.

`list_apps`

List apps uploaded to a cloud provider (BrowserStack App Automate, Sauce Labs App Storage, TestMu Real Device Cloud, TestingBot Storage, or Digital.ai Applications). Reads provider-specific credentials from environment.

`upload_app`

Upload a local .apk or .ipa to a cloud provider (BrowserStack, Sauce Labs, TestMu, TestingBot, or Digital.ai). Returns the app URL for use in start_session.

`get_screenshot`

Takes a screenshot of the current page or screen and returns a base64-encoded image, resized and compressed for model context limits.

`get_accessibility_tree`

Returns the page accessibility tree with roles, names, and selectors. Browser-only. Supports filtering by ARIA roles and pagination via limit/offset.

`get_tabs`

Lists all browser tabs with handle, title, URL, and which is active. Use before switch_tab to find the target handle or index. Browser-only.

`get_contexts`

Returns available automation contexts and the currently active one. Use before switch_context to discover NATIVE_APP and WEBVIEW_* targets. Mobile-only.

`get_app_state`

Returns the current state of a mobile app: not installed, not running, background, or foreground. Mobile-only.

`get_cookies`

Returns all cookies for the current session, or a single cookie by name. Use to verify auth state, session tokens, or feature flags after login flows.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

WebDriverIO MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with web browsers and mobile applications
using WebDriverIO. Automate Chrome, Firefox, Edge, and Safari browsers plus iOS and Android apps—all through a unified interface.

Installation

Setup

Option 1: Configure Claude Desktop or Claude Code (Recommended)

Add the following configuration to your Claude MCP settings:

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

Option 2: Global Installation

npm i -g @wdio/mcp

Then configure MCP:

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "wdio-mcp"
    }
  }
}

> Note: The npm package is @wdio/mcp, but the executable binary is wdio-mcp.

Restart Claude Desktop

⚠️ You may need to fully restart Claude Desktop. On Windows, use Task Manager to ensure it's completely closed before
restarting.

📖 Need help? Read the official MCP configuration guide

Prerequisites For Mobile App Automation

- Appium Server: Install globally with npm install -g appium
- Platform Drivers:
- iOS: appium driver install xcuitest (requires Xcode on macOS)
- Android: appium driver install uiautomator2 (requires Android Studio)
- Devices/Emulators:
- iOS Simulator (macOS) or physical device
- Android Emulator or physical device
- For iOS Real Devices: You'll need the device's UDID (Unique Device Identifier)
- Find UDID on macOS: Connect device → Open Finder → Select device → Click device name/model to reveal UDID
- Find UDID on Windows: Connect device → iTunes or Apple Devices app → Click device icon → Click "Serial Number"
to reveal UDID
- Xcode method: Window → Devices and Simulators → Select device → UDID shown as "Identifier"

Start the Appium server before using mobile features:

```bash
appium

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

start_session

attach_session

close_session

launch_chrome

emulate_device

navigate

switch_tab

switch_frame

scroll

click_element

set_value

set_cookie

delete_cookies

tap_element

swipe

drag_and_drop

switch_context

rotate_device

hide_keyboard

set_geolocation

execute_script

get_elements

open_web_extension

list_apps

upload_app

get_screenshot

get_accessibility_tree

get_tabs

get_contexts

get_app_state

get_cookies

Claude Desktop / Cursor

McpServers

WebDriverIO MCP Server

Installation

Setup

Prerequisites For Mobile App Automation

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sequential Thinking

Sentry

Github

`start_session`

`attach_session`

`close_session`

`launch_chrome`

`emulate_device`

`navigate`

`switch_tab`

`switch_frame`

`scroll`

`click_element`

`set_value`

`set_cookie`

`delete_cookies`

`tap_element`

`swipe`

`drag_and_drop`

`switch_context`

`rotate_device`

`hide_keyboard`

`set_geolocation`

`execute_script`

`get_elements`

`open_web_extension`

`list_apps`

`upload_app`

`get_screenshot`

`get_accessibility_tree`

`get_tabs`

`get_contexts`

`get_app_state`

`get_cookies`