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"]
}
}
}

Environment Variablesโ€‹

The server reads these variables from the environment that starts it.

VariableDefaultDescription
WDIO_MCP_TOOLSunsetSet to all to list every tool from startup. By default, tools that do not apply to the current session's platform, and tools in optional groups, stay hidden until a matching session starts or the client calls enable_tools. Use all for clients that ignore tool list changes.
WDIO_MCP_NETWORK_LOGSnoneDefault networkLogs for start_session: none, failures, or all. A networkLogs argument on the call overrides it. An invalid value fails server startup.
WDIO_MCP_CACHE_DIR~/.wdio-mcpDirectory for the cached WebdriverIO docs corpus used by query_docs and the wdio://docs/* resources.
APPIUM_URL127.0.0.1Hostname of the local Appium server, without a scheme.
APPIUM_URL_PORT4723Port of the local Appium server.
APPIUM_PATH/Base path of the local Appium server.
APPIUM_PROTOCOLhttpProtocol of the local Appium server.

appiumConfig on start_session overrides the APPIUM_* values for that session.

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" | "electron" | "ios" | "android"
Required
Yes

The platform to automate. See Electron Session Options for "electron".

providerโ€‹

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

Where the session runs. Use a cloud provider name for remote devices; each requires its own environment variables. Use external for any W3C WebDriver endpoint. 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. Values are provider-native and passed through unchanged; see Operating system values.

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
1280
Required
No
  • Range: 400 - 3840

Initial browser window width in pixels.

windowHeightโ€‹

Type
number
Default
800
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, cloud:<name> for Digital.ai) 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; protocol?: string }
Required
No

Appium server connection. Defaults to the APPIUM_* environment variables, or { host: "127.0.0.1", port: 4723, path: "/" } when they are unset.

Electron Session Optionsโ€‹

Options for platform: "electron" sessions. Electron runs locally only (provider: "local"), and the server manages its lifecycle: Electron sessions can't be attached, and close_session cannot detach them.

Point the session at the app with electronRootDir, or with capabilities containing wdio:electronServiceOptions with appBinaryPath or appEntryPoint.

electronRootDirโ€‹

Type
string
Required
Conditional

Project root used to discover the Electron Builder or Forge configuration. Required unless capabilities sets wdio:electronServiceOptions with appBinaryPath or appEntryPoint.

electronDeeplinkSchemeโ€‹

Type
string
Required
No

URI scheme without the colon (for example myapp) that trigger_electron_deeplink uses. Stored in lowercase.

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
Digital.aiDIGITALAI_CLOUD_URL (host)DIGITALAI_ACCESS_KEY

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). Only BrowserStack, Sauce Labs, TestMu, and TestingBot start tunnels; Digital.ai has no tunnel support, so the flag has no effect there.

  • 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. Digital.ai uses the session label, or the project label when none is set, as its test name; build is not sent.

traceโ€‹

Type
boolean
Default
false
Required
No

Enable trace recording. When the session closes, or a later start_session replaces it, the server writes a Playwright-compatible zip to .trace/ in the working directory, named <timestamp>-<id8>.zip. <timestamp> is the ISO time with : and . replaced by -, and <id8> is the first eight characters of the session ID. See Viewing Traces.

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, which is listed only for Electron sessions. Browsers use snapshot.

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

Viewing Tracesโ€‹

wdio-show-trace is a bin of the @wdio/mcp package. It serves one trace zip on a local port and opens it in the trace viewer at player.vibium.dev.

# Newest zip in ./.trace
npx -p @wdio/mcp wdio-show-trace

# A specific zip
npx -p @wdio/mcp wdio-show-trace path/to/trace.zip

Without a path, it opens the newest .zip in ./.trace by modification time. Press Ctrl+C to stop the server.

Session Behaviorโ€‹

Session Typesโ€‹

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

Named Sessionsโ€‹

The server can run several sessions at once. Every session has a session ID, and it can also have a name.

  • Give a session a name in start_session or attach_session. Names must be unique among live sessions.
  • onExisting: "close" (default) replaces the active session. onExisting: "keep" leaves the existing sessions running. A kept session does not become the default when one already exists, so target it by name.
  • Pass session (a name or a session ID) to any tool to target that session. Without it, the tool acts on the default session.
  • Results from a targeted call, or from any call while more than one session is live, start with [session: <name> (<id8>)]. Unnamed sessions show [session: <id8>].
  • A tool that does not apply to a session's platform returns an error for that session.
  • Names last only while the server process runs.
start_session({ name: "shop", platform: "browser", browser: "chrome", navigationUrl: "https://example.com" })
start_session({ name: "admin", onExisting: "keep", platform: "browser", browser: "firefox" })
snapshot({ session: "admin" })

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