Skip to main content

Configuration

This page documents all configuration options for the WebdriverIO MCP server.

MCP Server Configuration​

The MCP server is configured through the configuration files or commands.

Basic Configuration​

Edit your MCP configuration file (e.g. ./.mcp.json) and add the following:

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

Session Options​

All session options are passed to the start_session tool. There is a single unified tool for browser and mobile sessions; the platform parameter determines the session type.

Common Options​

platform​

Type
"browser" | "ios" | "android"
Required
Yes

The platform to automate.

provider​

Type
"local" | "browserstack" | "saucelabs" | "testmu" | "testingbot"
Default
"local"
Required
No

Where the session runs. Use a cloud provider name for remote devices; each requires its own environment variables. See Cloud Providers for details.

Browser Session Options​

Options for platform: "browser" sessions.

browser​

Type
"chrome" | "firefox" | "edge" | "safari"
Required
Yes (for browser platform)

Browser to launch.

browserVersion​

Type
string
Default
"latest"
Required
No

Browser version. Cloud providers only (default: latest).

os / osVersion​

Type
string
Required
No

Operating system for cloud provider browser sessions. Examples: os: "Windows", osVersion: "11" or os: "OS X", osVersion: "Sequoia".

headless​

Type
boolean
Default
true
Required
No

Run browser in headless mode (no visible window). Set to false to see the browser.

windowWidth​

Type
number
Default
1920
Required
No
  • Range: 400 - 3840

Initial browser window width in pixels.

windowHeight​

Type
number
Default
1080
Required
No
  • Range: 400 - 2160

Initial browser window height in pixels.

Type
string
Required
No

URL to navigate to immediately after starting the browser. More efficient than calling start_session followed by navigate separately.

attach​

Type
boolean
Default
false
Required
No

Attach to an existing Chrome instance instead of launching a new one. Use after launch_chrome to connect via CDP.

attachConfig​

Type
{ port?: number; host?: string }
Default
{ port: 9222, host: "localhost" }
Required
No

Chrome remote debugging connection config. Only applies when attach: true.

Mobile Session Options​

Options for platform: "ios" or platform: "android" sessions.

deviceName​

Type
string
Required
Yes (for mobile platforms)

Name of the device, simulator, or emulator.

Examples:

  • iOS Simulator: "iPhone 16", "iPad Air (5th generation)"
  • Android Emulator: "Pixel 7", "Nexus 5X"
  • Real Device: The device name as shown in your system

platformVersion​

Type
string
Required
No

OS version of the device/simulator/emulator (e.g., "18.0" for iOS, "14" for Android).

automationName​

Type
"XCUITest" | "UiAutomator2"
Required
No

Automation driver. Defaults to XCUITest for iOS and UiAutomator2 for Android.

udid​

Type
string
Required
No (Required for real iOS devices)

Unique Device Identifier. Required for real iOS devices (40-character identifier).

Finding UDID:

  • iOS: Connect device, open Finder, click on device → Serial Number (click to reveal UDID)
  • Android: Run adb devices in terminal

appPath​

Type
string
Required
No

Path to the application file to install and launch.

Supported formats:

  • iOS Simulator: .app directory
  • iOS Real Device: .ipa file
  • Android: .apk file

Either appPath must be provided, or noReset: true to connect to an already-running app.

app​

Type
string
Required
No

Cloud provider app URL (bs://... for BrowserStack, storage:filename= for Sauce Labs, lt://... for TestMu, TestingBot app_url) or customId. Used instead of appPath for cloud mobile sessions.

appWaitActivity​

Type
string
Required
No (Android only)

Activity to wait for on app launch. If not specified, the app's main/launcher activity is used.

Example: "com.example.app.MainActivity"

Session State Options​

noReset​

Type
boolean
Required
No

Preserve the app state between sessions. When true:

  • App data is preserved (login state, preferences, etc.)
  • Session will detach instead of close (keeps app running)
  • Can be used without appPath to connect to an already-running app

fullReset​

Type
boolean
Required
No

Completely reset the app before the session:

  • iOS: Uninstalls and reinstalls the app
  • Android: Clears app data and cache

Set fullReset: false with noReset: true to preserve app state completely.

Session Timeout​

newCommandTimeout​

Type
number
Default
300
Required
No

How long (in seconds) Appium will wait for a new command before ending the session. Increase for longer debugging sessions.

Automatic Handling​

autoGrantPermissions​

Type
boolean
Default
true
Required
No

Automatically grant app permissions on install/launch (camera, microphone, location, etc.).

Android Only

This option primarily affects Android. iOS permissions must be handled differently due to system restrictions.

autoAcceptAlerts​

Type
boolean
Default
true
Required
No

Automatically accept system alerts (dialogs) during automation ("Allow notifications?", etc.).

autoDismissAlerts​

Type
boolean
Default
false
Required
No

Dismiss system alerts instead of accepting them. Takes precedence over autoAcceptAlerts when true.

Appium Server Connection​

Override the Appium server connection on a per-session basis using appiumConfig:

start_session({
  platform: "ios",
  deviceName: "iPhone 16",
  appPath: "/path/to/app.app",
  appiumConfig: { host: "192.168.1.100", port: 4724, path: "/wd/hub" }
})

appiumConfig​

Type
{ host?: string; port?: number; path?: string }
Required
No

Appium server connection. Defaults to { host: "127.0.0.1", port: 4723, path: "/" }.

Cloud Provider Options​

Credentials​

Each cloud provider requires its own environment variables:

ProviderUsername VariableAccess Key Variable
BrowserStackBROWSERSTACK_USERNAMEBROWSERSTACK_ACCESS_KEY
Sauce LabsSAUCE_USERNAMESAUCE_ACCESS_KEY
TestMuTESTMU_USERNAMETESTMU_ACCESS_KEY
TestingBotTESTINGBOT_KEYTESTINGBOT_SECRET

Set these before starting the MCP server.

region​

Type
"us-west-1" | "eu-central-1" | "apac-southeast-1"
Default
"eu-central-1"
Required
No

Sauce Labs data center region. Ignored for other providers.

tunnel​

Type
boolean | "external"
Default
false
Required
No

Enable local tunnel routing for cloud provider sessions (accessing localhost, staging environments, internal services).

  • true — Auto-start the tunnel before the session and stop it on close
  • "external" — Tunnel already running externally; sets provider-appropriate flags only

Before using true, read the provider's local-binary resource (wdio://browserstack/local-binary, wdio://saucelabs/local-binary, wdio://testmu/local-binary, or wdio://testingbot/local-binary) for setup instructions specific to your OS and architecture.

tunnelName​

Type
string
Required
No

Tunnel identifier name. Required when tunnel: "external" to match the running tunnel. When tunnel: true, a unique name is auto-generated if not provided.

reporting​

Type
{ project?: string; build?: string; session?: string }
Required
No

Cloud provider session labels visible in the provider's dashboard. Works identically across BrowserStack, Sauce Labs, TestMu, and TestingBot.

trace​

Type
boolean
Default
false
Required
No

Enable trace recording. Produces a Playwright-compatible .trace zip file saved to .trace/ on close_session. View traces at player.vibium.dev.

Element Detection Options​

Options for the get_elements tool.

inViewportOnly​

Type
boolean
Default
false
Required
No

Only return elements visible in the current viewport. Set to true to reduce results on long pages.

includeContainers​

Type
boolean
Default
false
Required
No

Include container/layout elements in the results:

Android containers: ViewGroup, FrameLayout, LinearLayout, RelativeLayout, ConstraintLayout, ScrollView, RecyclerView

iOS containers: View, StackView, CollectionView, ScrollView, TableView

includeBounds​

Type
boolean
Default
false
Required
No

Include element bounding box coordinates (x, y, width, height) in the response.

Pagination​

limit​

Type
number
Default
0 (unlimited)
Required
No

Maximum number of elements to return.

offset​

Type
number
Default
0
Required
No

Number of elements to skip before returning results.

Example: Get elements 21–40:

Get elements with limit 20 and offset 20

Accessibility Tree Options​

Options for the get_accessibility_tree tool (browser-only).

limit​

Type
number
Default
0 (unlimited)
Required
No

Maximum number of nodes to return.

offset​

Type
number
Default
0
Required
No

Number of nodes to skip for pagination.

roles​

Type
string[]
Default
All roles
Required
No

Filter to specific accessibility roles.

Common roles: button, link, textbox, checkbox, radio, heading, img, listitem

Example: Get only buttons and links:

Get accessibility tree filtered to button and link roles

Screenshot​

The get_screenshot tool takes no parameters. Screenshots are automatically processed:

OptimizationValueDescription
Max dimension2000pxImages larger than 2000px are scaled down
Max file size1MBImages are compressed to stay under 1MB
FormatPNG/JPEGPNG with max compression; JPEG if needed for size

Session Behavior​

Session Types​

TypeDescriptionAuto-Detach
browserBrowser sessionNo
iosiOS app sessionYes (if noReset: true or no appPath)
androidAndroid app sessionYes (if noReset: true or no appPath)

Single-Session Model​

The MCP server operates with a single-session model:

  • Only one browser OR app session can be active at a time
  • Starting a new session will close/detach the current session
  • Session state is maintained globally across tool calls

Detach vs Close​

Actiondetach: false (Close)detach: true (Detach)
BrowserCloses browser completelyKeeps browser running, disconnects WebDriver
Mobile AppTerminates appKeeps app running in current state
Use CaseClean slate for next sessionPreserve state, manual inspection

Performance Considerations​

Browser Automation​

  • Headless mode is faster but doesn't render visual elements
  • Smaller window sizes reduce screenshot capture time
  • Element detection is optimized with a single script execution
  • Screenshot optimization keeps images under 1MB for efficient processing

Mobile Automation​

  • XML page source parsing uses only 2 HTTP calls (vs 600+ for traditional element queries)
  • Accessibility ID selectors are fastest and most reliable
  • XPath selectors are slowest; use only as a last resort
  • Pagination (limit and offset) reduces token usage for screens with many elements

Token Usage Tips​

SettingImpact
inViewportOnly: trueFilters off-screen elements, reducing response size
includeContainers: falseExcludes layout elements (ViewGroup, etc.)
includeBounds: falseOmits x/y/width/height data
limit with paginationProcess elements in batches instead of all at once

Appium Server Setup​

Before using mobile automation, ensure Appium is properly configured.

Basic Setup​

# Install Appium globally
npm install -g appium

# Install drivers
appium driver install xcuitest    # iOS
appium driver install uiautomator2  # Android

# Start the server
appium

Custom Server Configuration​

# Start with custom host and port
appium --address 0.0.0.0 --port 4724

# Start with logging
appium --log-level debug

# Start with specific base path
appium --base-path /wd/hub

Verify Installation​

# Check installed drivers
appium driver list --installed

# Check Appium version
appium --version

# Test connection
curl http://localhost:4723/status

Troubleshooting Configuration​

MCP Server Not Starting​

  1. Verify npm/npx is installed: npm --version
  2. Try running manually: npx @wdio/mcp
  3. Check your harness' logs for errors

Appium Connection Issues​

  1. Verify Appium is running: curl http://localhost:4723/status
  2. Check appiumConfig in start_session matches the Appium server settings
  3. Ensure firewall allows connections on the Appium port

Session Won't Start​

  1. Browser: Ensure the target browser is installed
  2. iOS: Verify Xcode and simulators are available
  3. Android: Check ANDROID_HOME and emulator is running
  4. Review Appium server logs for detailed error messages

Session Timeouts​

If sessions are timing out during debugging:

  1. Increase newCommandTimeout when starting the session
  2. Use noReset: true to preserve state between sessions
  3. Use detach: true when closing to keep the app running

Welcome! How can I help?

WebdriverIO AI Copilot