Configuration

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

MCP Server Configuration

The MCP server is configured through the Claude Desktop or Claude Code configuration files.

Basic Configuration

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Claude Code

Edit your project's .claude/settings.json:

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

Environment Variables

Configure the Appium server connection and other settings via environment variables.

Appium Connection

Example with Environment Variables

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"],
            "env": {
                "APPIUM_URL": "192.168.1.100",
                "APPIUM_URL_PORT": "4724",
                "APPIUM_PATH": "/wd/hub"
            }
        }
    }
}

Browser Session Options

Options available when starting a browser session via the start_browser tool.

headless

• Type: boolean
• Mandatory: No
• Default: false

Run Chrome in headless mode (no visible browser window). Useful for CI/CD environments or when you don't need to see the browser.

windowWidth

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

Initial browser window width in pixels.

windowHeight

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

Initial browser window height in pixels.

navigationUrl

• Type: string
• Mandatory: No

URL to navigate to immediately after starting the browser. This is more efficient than calling start_browser followed by navigate separately.

Example: Start browser and navigate in one call:

Start Chrome and navigate to https://webdriver.io

Mobile Session Options

Options available when starting a mobile app session via the start_app_session tool.

Platform Options

platform

• Type: string
• Mandatory: Yes
• Values: iOS | Android

The mobile platform to automate.

platformVersion

• Type: string
• Mandatory: No

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

automationName

• Type: string
• Mandatory: No
• Values: XCUITest (iOS), UiAutomator2 | Espresso (Android)

The automation driver to use. Defaults to XCUITest for iOS and UiAutomator2 for Android.

Device Options

deviceName

• Type: string
• Mandatory: Yes

Name of the device, simulator, or emulator to use.

Examples:

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

udid

• Type: string
• Mandatory: No (Required for real iOS devices)

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

Finding UDID:

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

App Options

appPath

• Type: string
• Mandatory: 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.

appWaitActivity

• Type: string
• Mandatory: 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
• Mandatory: No
• Default: false

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)
• Useful for testing user journeys across multiple sessions
• Can be used without appPath to connect to an already-running app

fullReset

• Type: boolean
• Mandatory: No
• Default: true

Completely reset the app before the session. When true:

• iOS: Uninstalls and reinstalls the app
• Android: Clears app data and cache
• Useful for starting with a clean state

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

Session Timeout

newCommandTimeout

• Type: number
• Mandatory: No
• Default: 60

How long (in seconds) Appium will wait for a new command before assuming the client has quit and ending the session. Increase this value for longer debugging sessions.

Examples:

• 60 - Default, suitable for most automation
• 300 - 5 minutes, for debugging or slower operations
• 600 - 10 minutes, for very long-running tests

Automatic Handling Options

autoGrantPermissions

• Type: boolean
• Mandatory: No
• Default: true

Automatically grant app permissions on install/launch. When true:

• Camera, microphone, location, etc. permissions are auto-granted
• No manual permission dialog handling needed
• Streamlines automation by avoiding permission popups

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

autoAcceptAlerts

• Type: boolean
• Mandatory: No
• Default: true

Automatically accept system alerts (dialogs) that appear during automation.

Examples of auto-accepted alerts:

• "Allow notifications?"
• "App would like to access your location"
• "Allow app to access photos?"

autoDismissAlerts

• Type: boolean
• Mandatory: No
• Default: false

Dismiss (cancel) system alerts instead of accepting them. Takes precedence over autoAcceptAlerts when set to true.

Appium Server Override

You can override the Appium server connection on a per-session basis:

appiumHost

• Type: string
• Mandatory: No

Appium server hostname. Overrides APPIUM_URL environment variable.

appiumPort

• Type: number
• Mandatory: No

Appium server port. Overrides APPIUM_URL_PORT environment variable.

appiumPath

• Type: string
• Mandatory: No

Appium server path. Overrides APPIUM_PATH environment variable.

Element Detection Options

Options for the get_visible_elements tool.

elementType

• Type: string
• Mandatory: No
• Default: interactable
• Values: interactable | visual | all

Type of elements to return:

• interactable: Buttons, links, inputs, and other clickable elements
• visual: Images, SVGs, and visual elements
• all: Both interactable and visual elements

inViewportOnly

• Type: boolean
• Mandatory: No
• Default: true

Only return elements that are visible within the current viewport. When false, returns all elements in the view hierarchy (useful for finding off-screen elements).

includeContainers

• Type: boolean
• Mandatory: No
• Default: false

Include container/layout elements in the results. When true:

Android containers included:

• ViewGroup, FrameLayout, LinearLayout
• RelativeLayout, ConstraintLayout
• ScrollView, RecyclerView

iOS containers included:

• View, StackView, CollectionView
• ScrollView, TableView

Useful for debugging layout issues or understanding the view hierarchy.

includeBounds

• Type: boolean
• Mandatory: No
• Default: false

Include element bounds/coordinates (x, y, width, height) in the response. Set to true for:

• Coordinate-based interactions
• Layout debugging
• Visual element positioning

Pagination Options

For large pages with many elements, use pagination to reduce token usage:

limit

• Type: number
• Mandatory: No
• Default: 0 (unlimited)

Maximum number of elements to return.

offset

• Type: number
• Mandatory: No
• Default: 0

Number of elements to skip before returning results.

Example: Get elements 21-40:

Get visible elements with limit 20 and offset 20

Accessibility Tree Options

Options for the get_accessibility tool (browser-only).

limit

• Type: number
• Mandatory: No
• Default: 100

Maximum number of nodes to return. Use 0 for unlimited (not recommended for large pages).

offset

• Type: number
• Mandatory: No
• Default: 0

Number of nodes to skip for pagination.

roles

• Type: string[]
• Mandatory: No
• Default: All roles

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

namedOnly

• Type: boolean
• Mandatory: No
• Default: true

Only return nodes that have a name/label. Filters out anonymous containers and reduces noise in the results.

Screenshot Options

Options for the take_screenshot tool.

outputPath

• Type: string
• Mandatory: No

Path where to save the screenshot file. If not provided, returns base64-encoded image data.

Automatic Optimization

Screenshots are automatically processed to optimize for LLM consumption:

This optimization ensures screenshots can be efficiently processed without exceeding token limits.

Session Behavior

Session Types

The MCP server tracks session types to provide appropriate tools and behavior:

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

Performance Considerations

The MCP server is optimized for efficient LLM communication using TOON (Token-Oriented Object Notation) format, which minimizes token usage when sending data to Claude.

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
• inViewportOnly: true (default) filters to only visible elements

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
• inViewportOnly: true (default) significantly reduces element count
• Pagination (limit and offset) reduces token usage for screens with many elements
• includeBounds: false (default) omits coordinate data unless needed

Token Usage Tips

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 Claude Desktop logs for errors

Appium Connection Issues

1. Verify Appium is running: curl http://localhost:4723/status
2. Check environment variables match Appium server settings
3. Ensure firewall allows connections on the Appium port

Session Won't Start

1. Browser: Ensure Chrome 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