# MCP (Model Context Protocol)

## What can it do?[​](#what-can-it-do "Direct link to 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?[​](#why-webdriverio-mcp "Direct link to 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`](https://www.npmjs.com/package/@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](/docs/mcp/tools.md) and [Configuration](/docs/mcp/configuration.md) options

info

NOTE For Mobile Apps Mobile automation requires a running Appium server with the appropriate drivers installed. See [Prerequisites](#prerequisites) for setup instructions.

## Installation[​](#installation "Direct link to 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[​](#usage-with-claude "Direct link to 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[​](#usage-with-claude-code "Direct link to 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[​](#quick-start-examples "Direct link to Quick Start Examples")

### Browser Automation[​](#browser-automation "Direct link to 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[​](#mobile-app-automation "Direct link to 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[​](#capabilities "Direct link to Capabilities")

### Browser Automation[​](#browser-automation-1 "Direct link to 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)[​](#mobile-app-automation-iosandroid "Direct link to 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[​](#cloud-providers "Direct link to 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[​](#prerequisites "Direct link to Prerequisites")

### Browser Automation[​](#browser-automation-2 "Direct link to Browser Automation")

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

### Mobile Automation[​](#mobile-automation "Direct link to Mobile Automation")

#### iOS[​](#ios "Direct link to iOS")

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

#### Android[​](#android "Direct link to Android")

1. **Install Android Studio** and set up Android SDK
2. **Set environment variables**:
   <!-- -->
   ```
   export ANDROID_HOME=$HOME/Library/Android/sdk
   export PATH=$PATH:$ANDROID_HOME/emulator
   export PATH=$PATH:$ANDROID_HOME/platform-tools
   ```
3. **Install Appium**:
   <!-- -->
   ```
   npm install -g appium
   ```
4. **Install the UiAutomator2 driver**:
   <!-- -->
   ```
   appium driver install uiautomator2
   ```
5. **Start the Appium server**:
   <!-- -->
   ```
   appium
   ```
6. **Create an emulator** via Android Studio → Virtual Device Manager
7. **Start the emulator** before running tests

## Architecture[​](#architecture "Direct link to Architecture")

### How It Works[​](#how-it-works "Direct link to 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[​](#session-management "Direct link to 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[​](#element-detection "Direct link to Element Detection")

#### Browser (Web)[​](#browser-web "Direct link to 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)[​](#mobile-native-apps "Direct link to 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[​](#selector-syntax "Direct link to Selector Syntax")

The MCP server supports multiple selector strategies. See [Selectors](/docs/mcp/selectors.md) for detailed documentation.

### Web (CSS/XPath)[​](#web-cssxpath "Direct link to 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)[​](#mobile-cross-platform "Direct link to 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[​](#available-tools "Direct link to Available Tools")

The MCP server provides 29 tools for browser and mobile automation. See [Tools](/docs/mcp/tools.md) 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[​](#mcp-resources "Direct link to MCP Resources")

In addition to tools, the server exposes live session state as MCP resources. See [Resources](/docs/mcp/resources.md) 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[​](#automatic-handling "Direct link to Automatic Handling")

### Permissions[​](#permissions "Direct link to 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 "Direct link to 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[​](#transport "Direct link to 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](/docs/mcp/transport.md) for full options including `--allowedHosts` and `--allowedOrigins`.

## Performance Optimization[​](#performance-optimization "Direct link to 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[​](#error-handling "Direct link to 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[​](#use-cases "Direct link to Use Cases")

### Quality Assurance[​](#quality-assurance "Direct link to Quality Assurance")

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

### Web Scraping & Data Extraction[​](#web-scraping--data-extraction "Direct link to Web Scraping & Data Extraction")

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

### Mobile App Testing[​](#mobile-app-testing "Direct link to Mobile App Testing")

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

### Integration Testing[​](#integration-testing "Direct link to Integration Testing")

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

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Browser won't start[​](#browser-wont-start "Direct link to 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[​](#appium-connection-failed "Direct link to 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[​](#ios-simulator-issues "Direct link to 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[​](#android-emulator-issues "Direct link to Android Emulator issues")

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

## Resources[​](#resources "Direct link to Resources")

* [Tools Reference](/docs/mcp/tools.md) - Complete list of available tools
* [Resources Reference](/docs/mcp/resources.md) - MCP resources for live session state
* [Selectors Guide](/docs/mcp/selectors.md) - Selector syntax documentation
* [Configuration](/docs/mcp/configuration.md) - Configuration options
* [Transport](/docs/mcp/transport.md) - HTTP transport setup
* [Cloud Providers](/docs/mcp/cloud-providers.md) - BrowserStack, Sauce Labs, TestMu, and TestingBot cloud integration
* [FAQ](/docs/mcp/faq.md) - Frequently asked questions
* [GitHub Repository](https://github.com/webdriverio/mcp) - Source code and issues
* [NPM Package](https://www.npmjs.com/package/@wdio/mcp) - Package on npm
* [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification