MCP (Model Context Protocol)

What can it do?

WebdriverIO MCP is a Model Context Protocol (MCP) server that enables AI assistants to automate and interact with web browsers and mobile applications.

Why WebdriverIO MCP?

Mobile-First: Unlike browser-only MCP servers, WebdriverIO MCP supports iOS and Android native app automation via Appium
Cross-Platform Selectors: Smart element detection generates multiple locator strategies (accessibility ID, XPath, UiAutomator, iOS predicates) automatically
WebdriverIO Ecosystem: Built on the battle-tested WebdriverIO framework with its rich ecosystem of services and reporters

It provides a unified interface for:

🖥️ Desktop Browsers (Chrome, Firefox, Edge, Safari, headed or headless)
📱 Native Mobile Apps (iOS Simulators / Android Emulators / Real Devices via Appium)
📳 Hybrid Mobile Apps (Native + WebView context switching via Appium)
☁️ Cloud Devices (BrowserStack, Sauce Labs, TestMu real device and browser clouds)

through the @wdio/mcp package.

This allows AI assistants to:

Launch and control browsers with configurable dimensions, headless mode, and optional initial navigation
Navigate websites and interact with elements (click, type, scroll)
Analyze page content via accessibility tree and visible elements detection with pagination support
Take screenshots automatically optimized (resized, compressed to max 1MB)
Manage cookies for session handling
Control mobile devices including gestures (tap, swipe, drag and drop)
Switch contexts in hybrid apps between native and webview
Execute scripts - JavaScript in browsers, Appium mobile commands on devices
Handle device features like rotation, keyboard, geolocation
and much more, see the Tools and Configuration options

info

NOTE For Mobile Apps Mobile automation requires a running Appium server with the appropriate drivers installed. See Prerequisites for setup instructions.

Installation

The easiest way to use @wdio/mcp is via npx without any local installation:

npx @wdio/mcp

Or install it globally:

npm install -g @wdio/mcp

Usage with Claude

To use WebdriverIO MCP with Claude, modify the configuration file:

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

After adding the configuration, restart your harness. The WebdriverIO MCP tools will be available for browser and mobile automation tasks.

Usage with Claude Code

Claude Code automatically detects MCP servers. You can configure it in your project's .claude/settings.json, or .mcp.json.

Or add it to .claude.json globally with executing:

claude mcp add --transport stdio wdio-mcp -- npx -y @wdio/mcp

Validate it by running the /mcp command inside claude code.

Quick Start Examples

Browser Automation

Ask Claude to automate browser tasks:

"Open Chrome and navigate to https://webdriver.io"
"Click the 'Get Started' button"
"Take a screenshot of the page"
"Find all visible links on the page"

Mobile App Automation

Ask Claude to automate mobile apps:

"Start my iOS app on the iPhone 15 simulator"
"Tap the login button"
"Swipe up to scroll down"
"Take a screenshot of the current screen"

Capabilities

Browser Automation

Feature	Description
Session Management	Launch Chrome, Firefox, Edge, or Safari in headed/headless mode with custom dimensions; attach to an existing Chrome instance via CDP
Navigation	Navigate to URLs; manage multiple tabs
Element Interaction	Click elements, type text, find elements by various selectors
Page Analysis	Get interactable elements (with pagination), accessibility tree (with role filtering)
Screenshots	Capture screenshots (auto-optimized to max 1MB)
Scrolling	Scroll up/down by configurable pixel amounts
Cookie Management	Get, set, and delete cookies
Device Emulation	Emulate mobile/tablet viewports in browser (BiDi required)
Script Execution	Execute custom JavaScript in browser context

Mobile App Automation (iOS/Android)

Feature	Description
Session Management	Launch apps on simulators, emulators, or real devices
Touch Gestures	Tap (element or coordinates), swipe, drag and drop
Element Detection	Smart element detection with multiple locator strategies and pagination
App Lifecycle	Get app state (foreground, background, not running, not installed)
Context Switching	Switch between native and webview contexts in hybrid apps
Device Control	Rotate device, keyboard control, GPS override
Permissions	Automatic permission and alert handling
Script Execution	Execute Appium mobile commands (pressKey, deepLink, shell, etc.)

Cloud Providers

Feature	Description
Browser Sessions	Run browser sessions on BrowserStack, Sauce Labs, TestMu, or TestingBot (Windows, macOS, Linux)
Mobile Sessions	Run app sessions on real devices via BrowserStack, Sauce Labs, TestMu, or TestingBot
App Management	Upload `.apk`/`.ipa` files; list previously uploaded apps across all four providers
Local Tunnel	Auto-manage provider-specific tunnel binaries for accessing localhost
Reporting	Tag sessions with project/build/session labels (works identically across all providers)

Prerequisites

Browser Automation

Chrome, Firefox, Edge, or Safari must be installed
WebdriverIO handles automated driver management

Mobile Automation

iOS

Install Xcode from the Mac App Store
Install Xcode Command Line Tools:
```
xcode-select --install
```
Install Appium:
```
npm install -g appium
```
Install the XCUITest driver:
```
appium driver install xcuitest
```
Start the Appium server:
```
appium
```
For Simulators: Open Xcode → Window → Devices and Simulators to create/manage simulators
For Real Devices: You'll need the device UDID (40-character unique identifier)

Android

Install Android Studio and set up Android SDK

Set environment variables:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Install Appium:
```
npm install -g appium
```
Install the UiAutomator2 driver:
```
appium driver install uiautomator2
```
Start the Appium server:
```
appium
```
Create an emulator via Android Studio → Virtual Device Manager
Start the emulator before running tests

Architecture

How It Works

WebdriverIO MCP acts as a bridge between AI assistants and browser/mobile automation:

┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│  Claude Desktop │ ◄──────────────────►  │    @wdio/mcp    │
│  or Claude Code │   (stdio or HTTP)     │     Server      │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                             WebDriverIO API
                                                   │
                    ┌──────────────────────────────┼──────────────────────────────┐
                    │                              │                              │
            ┌───────▼───────┐             ┌───────▼───────┐             ┌───────▼───────┐
            │    Browser    │             │    Appium     │             │   Cloud        │
            │ (local/CDP)   │             │  (iOS/Android)│             │   Providers    │
            └───────────────┘             └───────────────┘             └───────────────┘

Session Management

Single-session model: Only one browser OR app session can be active at a time
Session state is maintained globally across tool calls
Auto-detach: Sessions with preserved state (noReset: true) automatically detach on close

Element Detection

Browser (Web)

Uses an optimized browser script to find all visible, interactable elements
Returns elements with CSS selectors, IDs, classes, and ARIA information
Supports viewport filtering and pagination

Mobile (Native Apps)

Uses efficient XML page source parsing (2 HTTP calls vs 600+ for traditional queries)
Platform-specific element classification for Android and iOS
Generates multiple locator strategies per element:
- Accessibility ID (cross-platform, most stable)
- Resource ID / Name attribute
- Text / Label matching
- XPath (full and simplified)
- UiAutomator (Android) / Predicates (iOS)

Selector Syntax

The MCP server supports multiple selector strategies. See Selectors for detailed documentation.

Web (CSS/XPath)

# CSS Selectors
button.my-class
#element-id
[data-testid="login"]

# XPath
//button[@class='submit']
//a[contains(text(), 'Click')]

# Text Selectors (WebdriverIO specific)
button=Exact Button Text
a*=Partial Link Text

Mobile (Cross-Platform)

# Accessibility ID (recommended - works on iOS & Android)
~loginButton

# Android UiAutomator
android=new UiSelector().text("Login")

# iOS Predicate String
-ios predicate string:label == "Login"

# iOS Class Chain
-ios class chain:**/XCUIElementTypeButton[`label == "Login"`]

# XPath (works on both platforms)
//android.widget.Button[@text="Login"]
//XCUIElementTypeButton[@label="Login"]

Available Tools

The MCP server provides 29 tools for browser and mobile automation. See Tools for the complete reference.

Tool	Platform	Description
`start_session`	all	Start a browser or mobile session (local or cloud provider)
`close_session`	all	Close or detach from the current session
`launch_chrome`	browser	Open Chrome with remote debugging for CDP attach
`navigate`	browser	Load a URL in the current tab
`get_tabs`	browser	List all open tabs
`switch_tab`	browser	Focus a tab by handle or index
`switch_frame`	browser	Switch into an iframe by selector, or back to top-level
`click_element`	browser	Click an element
`set_value`	all	Type text into an input
`scroll`	browser	Scroll the page up or down
`get_elements`	all	Get interactable elements (with filtering + pagination)
`get_accessibility_tree`	browser	Get accessibility tree (with role filtering)
`get_screenshot`	all	Capture screenshot (auto-optimized)
`get_cookies`	browser	Get all cookies or a specific cookie
`set_cookie`	browser	Set a browser cookie
`delete_cookies`	browser	Delete all or one cookie
`emulate_device`	browser	Emulate a mobile/tablet device viewport
`execute_script`	all	Run JavaScript (browser) or Appium commands (mobile)
`tap_element`	mobile	Tap an element or screen coordinates
`swipe`	mobile	Swipe gesture in a direction
`drag_and_drop`	mobile	Drag between elements or coordinates
`get_contexts`	mobile	List available native/webview contexts
`switch_context`	mobile	Switch between native and webview contexts
`rotate_device`	mobile	Rotate to portrait or landscape
`hide_keyboard`	mobile	Dismiss the software keyboard
`set_geolocation`	all	Override device GPS coordinates
`get_app_state`	mobile	Get app lifecycle state
`list_apps`	cloud	List uploaded apps (BrowserStack, Sauce Labs, TestMu, TestingBot)
`upload_app`	cloud	Upload an `.apk`/`.ipa` to a cloud provider

MCP Resources

In addition to tools, the server exposes live session state as MCP resources. See Resources for the complete reference.

Resource URI	Description
`wdio://sessions`	Index of all sessions
`wdio://session/current/elements`	Interactable elements (prefer over screenshot)
`wdio://session/current/screenshot`	Screenshot as base64
`wdio://session/current/accessibility`	Accessibility tree
`wdio://session/current/cookies`	Browser cookies
`wdio://session/current/tabs`	Open browser tabs
`wdio://session/current/contexts`	Available mobile contexts
`wdio://session/current/context`	Active mobile context
`wdio://session/current/app-state/{bundleId}`	Mobile app lifecycle state
`wdio://session/current/geolocation`	Current GPS override
`wdio://session/current/logs`	Session logs (browser console, logcat, crashlog)
`wdio://session/current/capabilities`	Raw WebDriver capabilities
`wdio://session/current/code`	Generated WebdriverIO JS
`wdio://session/current/steps`	Session step log
`wdio://session/{sessionId}/code`	Generated JS for past session
`wdio://session/{sessionId}/steps`	Steps for past session
`wdio://browserstack/local-binary`	BrowserStack Local setup instructions
`wdio://saucelabs/local-binary`	Sauce Connect Proxy setup instructions
`wdio://testmu/local-binary`	TestMu Tunnel setup instructions
`wdio://testingbot/local-binary`	TestingBot Tunnel setup instructions

Automatic Handling

Permissions

By default, the MCP server automatically grants app permissions (autoGrantPermissions: true), eliminating the need to manually handle permission dialogs during automation.

System Alerts

System alerts (like "Allow notifications?") are automatically accepted by default (autoAcceptAlerts: true). This can be configured to dismiss instead with autoDismissAlerts: true.

Transport

By default, the server runs over stdio (launched as a subprocess by the AI client). For clients that don't support subprocess-based MCP (llama.cpp, Codex secure mode), use HTTP transport:

npx @wdio/mcp --http --port 3000

See Transport for full options including --allowedHosts and --allowedOrigins.

Performance Optimization

The MCP server is optimized for efficient AI assistant communication:

TOON Format: Uses Token-Oriented Object Notation for minimal token usage
XML Parsing: Mobile element detection uses 2 HTTP calls (vs 600+ traditionally)
Screenshot Compression: Images auto-compressed to max 1MB
Viewport Filtering: Only visible elements returned by default
Pagination: Large element lists can be paginated to reduce response size

Error Handling

All tools are designed with robust error handling:

Errors are returned as text content (never thrown), maintaining MCP protocol stability
Descriptive error messages help diagnose issues
Session state is preserved even when individual operations fail

Use Cases

Quality Assurance

AI-powered test case execution
Visual regression testing with screenshots
Accessibility auditing via accessibility tree analysis

Web Scraping & Data Extraction

Navigate complex multi-page flows
Extract structured data from dynamic content
Handle authentication and session management

Mobile App Testing

Cross-platform test automation (iOS + Android)
Onboarding flow validation
Deep linking and navigation testing

Integration Testing

End-to-end workflow testing
API + UI integration verification
Multi-platform consistency checks

Troubleshooting

Browser won't start

Ensure the target browser is installed
Check that no other process is using the default debugging port (9222)
Try headless mode if display issues occur

Appium connection failed

Verify Appium server is running (appium)
Check the Appium host and port in appiumConfig
Ensure the appropriate driver is installed (appium driver list)

iOS Simulator issues

Ensure Xcode is installed and up to date
Check that simulators are available (xcrun simctl list devices)
For real devices, verify the UDID is correct

Android Emulator issues

Ensure Android SDK is properly configured
Verify emulator is running (adb devices)
Check that ANDROID_HOME environment variable is set

Resources

Tools Reference - Complete list of available tools
Resources Reference - MCP resources for live session state
Selectors Guide - Selector syntax documentation
Configuration - Configuration options
Transport - HTTP transport setup
Cloud Providers - BrowserStack, Sauce Labs, TestMu, and TestingBot cloud integration
FAQ - Frequently asked questions
GitHub Repository - Source code and issues
NPM Package - Package on npm
Model Context Protocol - MCP specification

What can it do?​

Why WebdriverIO MCP?​

Installation​

Usage with Claude​

Usage with Claude Code​

Quick Start Examples​

Browser Automation​

Mobile App Automation​

Capabilities​

Browser Automation​

Mobile App Automation (iOS/Android)​

Cloud Providers​

Prerequisites​

Browser Automation​

Mobile Automation​

iOS​

Android​

Architecture​

How It Works​

Session Management​

Element Detection​

Browser (Web)​

Mobile (Native Apps)​

Selector Syntax​

Web (CSS/XPath)​

Mobile (Cross-Platform)​

Available Tools​

MCP Resources​

Automatic Handling​

Permissions​

System Alerts​

Transport​

Performance Optimization​

Error Handling​

Use Cases​

Quality Assurance​

Web Scraping & Data Extraction​

Mobile App Testing​

Integration Testing​

Troubleshooting​

Browser won't start​

Appium connection failed​

iOS Simulator issues​

Android Emulator issues​

Resources​

What can it do?

Why WebdriverIO MCP?

Installation

Usage with Claude

Usage with Claude Code

Quick Start Examples

Browser Automation

Mobile App Automation

Capabilities

Browser Automation

Mobile App Automation (iOS/Android)

Cloud Providers

Prerequisites

Browser Automation

Mobile Automation

iOS

Android

Architecture

How It Works

Session Management

Element Detection

Browser (Web)

Mobile (Native Apps)

Selector Syntax

Web (CSS/XPath)

Mobile (Cross-Platform)

Available Tools

MCP Resources

Automatic Handling

Permissions

System Alerts

Transport

Performance Optimization

Error Handling

Use Cases

Quality Assurance

Web Scraping & Data Extraction

Mobile App Testing

Integration Testing

Troubleshooting

Browser won't start

Appium connection failed

iOS Simulator issues

Android Emulator issues

Resources