WebdriverIO MCP

WebDriverIO MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 助手使用 WebdriverIO 与 Web 浏览器、本地 Electron 应用和移动应用交互。通过统一接口自动化 Chrome、Firefox、Edge、Safari、Electron、iOS 和 Android。

安装

将以下配置添加到 MCP 客户端设置中：

标准配置（适用于大多数客户端）：

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

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

claude mcp add wdio-mcp -- npx -y @wdio/mcp@latest

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

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

codex mcp add wdio-mcp npx "@wdio/mcp@latest"

[mcp_servers.wdio-mcp]
command = "npx"
args = ["@wdio/mcp@latest"]

goose configure

extensions:
  wdio-mcp:
    name: WebDriverIO MCP
    cmd: npx
    args: [ -y, "@wdio/mcp@latest" ]
    enabled: true
    type: stdio

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

{
  "context_servers": {
    "wdio-mcp": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "@wdio/mcp@latest"
      ]
    }
  }
}

code --add-mcp '{"name":"wdio-mcp","command":"npx","args":["-y","@wdio/mcp@latest"]}'

⚠️ 需要重启：添加配置后，请完全重启 MCP 客户端以应用更改。

选项 2：全局安装

如果希望全局安装：

npm install -g @wdio/mcp

然后使用 wdio-mcp 作为命令：

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "wdio-mcp"
    }
  }
}

📖 **需要帮助？**请参阅 MCP 安装指南。

HTTP 传输（适用于非子进程客户端）

默认情况下，服务使用 stdio（子进程）传输。对于无法启动子进程的客户端（例如 llama.cpp、OpenAI Codex 安全模式），请启用 HTTP 传输：

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

然后将 MCP 客户端指向 http://localhost:3000/mcp。

移动应用自动化的先决条件

• Appium Server：使用 npm install -g appium 全局安装
• 平台驱动程序：
  • iOS：appium driver install xcuitest（需要在 macOS 上安装 Xcode）
  • Android：appium driver install uiautomator2（需要安装 Android Studio）
• 设备/模拟器：
  • iOS 模拟器（macOS）或实体设备
  • Android 模拟器或实体设备
• iOS 实体设备：需要设备的 UDID（唯一设备标识符）
  • 在 macOS 上查找 UDID：连接设备 → 打开 Finder → 选择设备 → 点击设备名称/型号以显示 UDID
  • 在 Windows 上查找 UDID：连接设备 → 打开 iTunes 或 Apple Devices 应用 → 点击设备图标 → 点击“Serial Number” 以显示 UDID
  • Xcode 方法：Window → Devices and Simulators → 选择设备 → UDID 显示为“Identifier”

使用移动功能前，请先启动 Appium 服务器：

appium
# Server runs at http://127.0.0.1:4723 by default

云端提供商

无需任何本地设置，即可在云端实体设备和浏览器上运行浏览器和移动应用测试。目前支持 BrowserStack、Sauce Labs、 LambdaTest、TestingBot 和 Digital.ai Testing。

先决条件

将提供商凭据设置为环境变量，或配置在 MCP 客户端中：

export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "npx",
      "args": ["-y", "@wdio/mcp@latest"],
      "env": {
        "BROWSERSTACK_USERNAME": "your_username",
        "BROWSERSTACK_ACCESS_KEY": "your_access_key"
      }
    }
  }
}

export SAUCE_USERNAME=your_username
export SAUCE_ACCESS_KEY=your_access_key

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "npx",
      "args": ["-y", "@wdio/mcp@latest"],
      "env": {
        "SAUCE_USERNAME": "your_username",
        "SAUCE_ACCESS_KEY": "your_access_key"
      }
    }
  }
}

export TESTMU_USERNAME=your_username
export TESTMU_ACCESS_KEY=your_access_key

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "npx",
      "args": ["-y", "@wdio/mcp@latest"],
      "env": {
        "TESTMU_USERNAME": "your_username",
        "TESTMU_ACCESS_KEY": "your_access_key"
      }
    }
  }
}

export TESTINGBOT_KEY=your_key
export TESTINGBOT_SECRET=your_secret

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "npx",
      "args": ["-y", "@wdio/mcp@latest"],
      "env": {
        "TESTINGBOT_KEY": "your_key",
        "TESTINGBOT_SECRET": "your_secret"
      }
    }
  }
}

export DIGITALAI_CLOUD_URL=https://your-cloud.example.com
export DIGITALAI_ACCESS_KEY=your_access_key

{
  "mcpServers": {
    "wdio-mcp": {
      "command": "npx",
      "args": ["-y", "@wdio/mcp@latest"],
      "env": {
        "DIGITALAI_CLOUD_URL": "https://your-cloud.example.com",
        "DIGITALAI_ACCESS_KEY": "your_access_key"
      }
    }
  }
}

start_session({
  provider: 'digitalai', platform: 'browser', browser: 'chrome', os: 'Windows 10',
  capabilities: { 'wdio:enforceWebDriverClassic': true }
})

浏览器会话

在特定的 OS/版本组合上运行浏览器：

// BrowserStack
start_session({
    provider: 'browserstack',
    platform: 'browser',
    browser: 'chrome',           // chrome | firefox | edge | safari
    browserVersion: 'latest',    // default: latest
    os: 'Windows',               // e.g. "Windows", "OS X"
    osVersion: '11',             // e.g. "11", "Sequoia"
    reporting: {
        project: 'My Project',
        build: 'v1.2.0',
        session: 'Login flow'
    }
})

// Sauce Labs
start_session({
    provider: 'saucelabs',
    platform: 'browser',
    browser: 'chrome',
    os: 'Windows',               // combined with osVersion → platformName
    osVersion: '11',             // e.g. "11", "15" (numbered Mac naming)
    region: 'eu-central-1',      // default: eu-central-1
    reporting: {
        build: 'v1.2.0',
        session: 'Login flow'
    }
})

// LambdaTest
start_session({
    provider: 'testmu',
    platform: 'browser',
    browser: 'chrome',
    os: 'Windows',               // combined with osVersion → platformName
    osVersion: '11',             // e.g. "11", "Sequoia" (optional)
    reporting: {
        project: 'My Project',
        build: 'v1.2.0',
        session: 'Login flow'
    }
})

// TestingBot
start_session({
    provider: 'testingbot',
    platform: 'browser',
    browser: 'chrome',
    os: 'Windows',               // combined with osVersion → platformName (default: Windows 11)
    osVersion: '11',
    reporting: {
        build: 'v1.2.0',
        session: 'Login flow'
    }
})

// Digital.ai
start_session({
    provider: 'digitalai',
    platform: 'browser',
    browser: 'chrome',
    os: 'Windows',               // combined with osVersion → digitalai:osName (optional)
    osVersion: '11',
    reporting: {
        session: 'Login flow'    // → digitalai:testName (flat capability, not nested)
    }
})

各提供商对 os / osVersion 的处理方式：

• BrowserStack — os 和 osVersion 分别映射到 bstack:options.os / bstack:options.osVersion 字段。
• Sauce Labs / LambdaTest / TestingBot — os 和 osVersion 会合并到 W3C platformName capability 中（例如，os: 'Windows' + osVersion: '11' → platformName: 'Windows 11'）。这些提供商使用 "Windows 11"、"MacOS Sequoia" 或 "Linux" 之类的 platformName 值。省略 os 时，TestingBot 默认为 Windows 11。
• Digital.ai — os 和 osVersion 会合并到扁平的 digitalai:osName capability（而非 platformName）中，例如 os: 'Windows' + osVersion: '11' → digitalai:osName: 'Windows 11'。

移动应用会话

在云端真实设备上进行测试。先上传应用（或使用已有的应用 URL）：

// BrowserStack: returns bs:// URL
upload_app({ provider: 'browserstack', path: '/path/to/app.apk' })

// Sauce Labs: returns storage:filename= reference
upload_app({ provider: 'saucelabs', path: '/path/to/app.apk' })

// LambdaTest: returns lt:// URL
upload_app({ provider: 'testmu', path: '/path/to/app.apk' })

// TestingBot: returns tb:// URL
upload_app({ provider: 'testingbot', path: '/path/to/app.apk' })

// Digital.ai: returns cloud:<package-or-bundle> reference
upload_app({ provider: 'digitalai', path: '/path/to/app.apk' })

// Start a session
start_session({
    provider: 'browserstack',
    platform: 'android',
    app: 'bs://abc123...',
    deviceName: 'Samsung Galaxy S23',
    platformVersion: '13.0'
})

// Sauce Labs native app
start_session({
    provider: 'saucelabs',
    platform: 'android',
    app: 'storage:filename=myapp.apk',
    deviceName: 'Samsung.*',
    platformVersion: '16'
})

// LambdaTest native app
start_session({
    provider: 'testmu',
    platform: 'android',
    app: 'lt://abc123...',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// TestingBot native app
start_session({
    provider: 'testingbot',
    platform: 'android',
    app: 'tb://abc123...',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// Digital.ai native app — devices are selected via a deviceQuery
start_session({
    provider: 'digitalai',
    platform: 'android',
    app: 'cloud:com.example.app',
    deviceQuery: "@os='android' and @version='14' and @name='.*Pixel.*'"
    // or omit deviceQuery and pass deviceName / platformVersion to build one
})

移动浏览器会话

在云端移动设备（真实设备或模拟器）上运行浏览器，无需上传应用：

// BrowserStack — Chrome on Android emulator
start_session({
    provider: 'browserstack',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Google Pixel 7',
    platformVersion: '13'
})

// Sauce Labs — Safari on iOS simulator
start_session({
    provider: 'saucelabs',
    platform: 'ios',
    browser: 'safari',
    deviceName: 'iPhone 15',
    platformVersion: '18',
    region: 'eu-central-1'
})

// LambdaTest — Chrome on Android emulator
start_session({
    provider: 'testmu',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// TestingBot — Chrome on Android emulator
start_session({
    provider: 'testingbot',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Pixel 7',
    platformVersion: '13'
})

// Digital.ai — Chrome on an Android device (real or emulator; selected via a deviceQuery)
start_session({
    provider: 'digitalai',
    platform: 'android',
    browser: 'chrome',
    deviceName: 'Pixel 7',
    platformVersion: '13'
    // or omit deviceName / platformVersion and pass deviceQuery directly, e.g.
    // deviceQuery: "@os='android' and @emulator='true'" to force an emulator
})

注意： 移动浏览器会话无需设置 app、appPath 或 noReset。提供商会直接在选定的设备（真实设备或模拟器）上启动浏览器。

使用 list_apps 查看之前上传的应用：

list_apps({ provider: 'browserstack' })
list_apps({ provider: 'saucelabs', sortBy: 'app_name' })
list_apps({ provider: 'testmu' })
list_apps({ provider: 'testingbot' })
list_apps({ provider: 'digitalai' })
list_apps({ provider: 'browserstack', organizationWide: true })

本地隧道

要测试只能通过本机或内部网络访问的 URL，请启用本地隧道：

// Auto-start tunnel (provider manages lifecycle)
start_session({
    provider: 'saucelabs',
    platform: 'browser',
    tunnel: true                  // auto-starts tunnel before session
})

// Use an already-running tunnel
start_session({
    provider: 'saucelabs',
    platform: 'browser',
    tunnel: 'external'            // uses existing tunnel
})

tunnel 参数取代已弃用的 browserstackLocal、saucelabsLocal 和 testmuLocal 参数。将其设为 true 可自动启动隧道（会在会话结束后自动停止），或设为 'external' 以使用已在本机运行的隧道。

注意：使用 tunnel: true 时，提供商会为你下载并管理隧道二进制文件。使用 tunnel: 'external' 时，则需要自行运行隧道；wdio://saucelabs/local-binary、wdio://testmu/local-binary 和 wdio://testingbot/local-binary 资源提供下载 URL 和设置说明。TestingBot Tunnel 是一个跨平台的 Java JAR 文件（需要 Java 11+），而不是针对各个平台分别提供的二进制文件。

报告标签

所有会话类型都支持 reporting 标签，这些标签会显示在提供商的控制面板中：

云提供商工具

这两个工具都需要 provider 参数（'browserstack'、'saucelabs'、'testmu'、'testingbot' 或 'digitalai'）。

功能

浏览器自动化

• 会话管理：启动和关闭浏览器会话（Chrome、Firefox、Edge、Safari），支持无头/有头模式
• 导航与交互：访问 URL、点击元素、填写表单并检索内容
• 页面分析：获取可见元素和无障碍树，并截取屏幕截图
• Cookie 管理：获取、设置和删除 Cookie
• 滚动：按可配置的距离平滑滚动
• 附加到正在运行的 Chrome：通过 --remote-debugging-port 连接到现有 Chrome 窗口，非常适合测试已通过身份验证或预先配置的会话
• 连接到现有 WebDriver 端点：重复使用已在运行的兼容 Selenium 的 WebDriver 端点，例如由框架管理的浏览器或桌面 WebView 自动化桥接（如 Tauri）
• 设备模拟：应用手机/平板预设（iPhone 15、Pixel 7 等），无需实体设备即可模拟响应式布局
• 会话录制：所有工具调用都会自动录制，并可导出为可运行的 WebdriverIO JS

移动应用自动化（iOS/Android）

• 原生应用测试：通过 Appium 测试 iOS（.app/.ipa）和 Android（.apk）应用
• 触控手势：点按、滑动、长按、拖放
• 应用生命周期：启动、切换到后台、终止应用并检查应用状态
• 上下文切换：在混合应用的原生和 WebView 上下文之间无缝切换
• 设备控制：旋转、锁定/解锁、地理位置、键盘控制、通知
• 跨平台选择器：无障碍 ID、XPath、UiAutomator（Android）、谓词（iOS）

可用工具

服务器只会列出适用于当前会话的工具：浏览器会话可使用下方的页面工具，移动会话可使用手势和设备工具，Electron 会话可使用 Electron 工具。较少使用的工具组（模拟、Cookie、设备仿真、扩展、附加、原始元素列表、云应用上传）会在 Agent 调用 enable_tools 后列出，因此不会在每次请求中都发送其定义。设置 WDIO_MCP_TOOLS=all 可一次性列出所有工具。

会话管理

导航与页面交互（Web 和移动端）

元素交互（Web 和移动端）

在浏览器和应用中，click_element、set_value、tap_element 和 perform_actions 既接受来自 snapshot 的引用（e12），也接受选择器。每项操作的结果都会列出页面或屏幕上的更改：新增或发生变化的元素及其引用，或导航到的页面。Agent 通常无需单独截屏或获取快照即可查看操作效果。

推荐工作流（也会作为服务器指令发送给客户端）：

• 先执行 snapshot，然后使用引用进行操作。
• 连续执行多个步骤（例如填写表单后提交）：调用一次 perform_actions。
• 页面未发生变化时，最新结果中的引用仍然有效。

Cookie 管理（Web，启用 enable_tools 后）

移动端手势（iOS/Android）

上下文切换（混合应用）

设备控制（iOS/Android）

文档搜索

MCP 资源（只读，无需调用工具）

使用示例

真实测试用例

示例 1：测试 Android 演示应用（图书扫描）

Test the Demo Android app at C:\Users\demo-liveApiGbRegionNonMinifiedRelease-3018788.apk on emulator-5554:
1. Start the app with auto-grant permissions
2. Get visible elements on the onboarding screen
3. Tap "Skip" to bypass onboarding
4. Verify main screen loads
5. Take a screenshot

示例 2：测试 World of Books 电商网站

You are a Testing expert, and want to assess the basic workflows of worldofbooks.com:
- Open World of Books (accept all cookies)
- Get visible elements to see navigation structure
- Search for a fiction book
- Choose one and validate if there are NEW and used book options
- Report your findings at the end

浏览器自动化

基础 Web 测试提示词：

You are a Testing expert, and want to assess the basic workflows of a web application:
- Open World of Books (accept all cookies)
- Search for a fiction book
- Choose one and validate if there are NEW and used book options
- Report your findings at the end

浏览器配置选项：

// Default settings (headed mode, 1280x1080)
start_session({platform: 'browser'})

// Firefox
start_session({platform: 'browser', browser: 'firefox'})

// Edge
start_session({platform: 'browser', browser: 'edge'})

// Safari (headed only; requires macOS)
start_session({platform: 'browser', browser: 'safari'})

// Headless mode
start_session({platform: 'browser', headless: true})

// Custom dimensions
start_session({platform: 'browser', windowWidth: 1920, windowHeight: 1080})

// Pass custom capabilities (e.g. Chrome extensions, profile, prefs)
start_session({
    platform: 'browser',
    headless: false,
    capabilities: {
        'goog:chromeOptions': {
            args: ['--user-data-dir=/tmp/wdio-mcp-profile', '--load-extension=/path/to/unpacked-extension']
        }
    }
})

模拟

通过 mock、get_mock_calls 和 manage_mock 可使用模拟功能（在 enable_tools({ groups: ['mocks'] }) 后列出），适用于 Electron 主进程 API 函数和浏览器网络请求。

mockType 接受 'electron' 或 'browser'。在 WebDriver 会话中，省略 mockType 时默认使用浏览器模拟。Electron 会话需要明确选择，因为它们可以针对这两种模拟。iOS/Android Appium 会话不支持模拟。

mock({
  mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog',
  behavior: 'mockResolvedValue', value: { canceled: false, filePaths: ['/tmp/example.txt'] }
})
// Interact with the renderer to open the application's file picker, then inspect its calls.
get_mock_calls({ mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog' })
manage_mock({ mockType: 'electron', apiName: 'dialog', funcName: 'showOpenDialog', action: 'restore' })

Electron 的 behavior 默认为 mockReturnValue；mockResolvedValue 和 mockRejectedValue 支持异步 API。每种行为都有一个 Once 变体，用于排队返回响应。重复配置会保留现有模拟和调用历史记录。值必须是 JSON；若值为 undefined，请省略 value。clear 会清除调用历史记录，reset 还会移除行为和排队响应，而 restore 会恢复原始函数。这些工具支持单个 API 函数；不提供类模拟和任意模拟实现。

浏览器模拟会拦截与 url glob 匹配的网络请求（例如 **/api/todos），并可选用 method 进行筛选。behavior 是可选的：省略时，只会被动记录匹配的请求，不会对其进行修改——模拟仍会放行每个请求。respond 和 respondOnce 需要 value（JSON 响应正文），并可选接受 statusCode 和 headers；abort/abortOnce 会使请求失败，而 redirect/redirectOnce 会将请求发送到 value 中的 URL。get_mock_calls 会为拦截的请求返回 { calls, callCount }，而 manage_mock 接受 clear、reset 或 restore。

start_session({ platform: 'browser', browser: 'chrome', capabilities: { webSocketUrl: true } })

// Observe-only: record every request to /api/todos without changing responses.
mock({ mockType: 'browser', url: '**/api/todos' })
navigate({ url: 'https://example.com/todos' })
get_mock_calls({ mockType: 'browser', url: '**/api/todos' })

// Or overwrite the response instead.
mock({ mockType: 'browser', url: '**/api/todos', method: 'GET', behavior: 'respond', value: [{ id: 1, title: 'Buy milk' }], statusCode: 200 })

// Interact with the page, then inspect the intercepted requests.
get_mock_calls({ mockType: 'browser', url: '**/api/todos', method: 'GET' })
manage_mock({ mockType: 'browser', url: '**/api/todos', method: 'GET', action: 'restore' })

浏览器模拟需要启用 BiDi 的会话——请使用 capabilities: { webSocketUrl: true } 启动会话。附加会话默认关闭 BiDi，因此其中的浏览器模拟无法使用，除非附加会话协商启用了 BiDi；在 Electron 会话中，浏览器模拟也需要 BiDi。句柄属于当前活动的浏览器会话，在会话关闭或被替换后无法复用。所有这三个工具都会参与追踪和生成的回放。

Electron 应用

Electron 支持仅限本地，并使用官方的 @wdio/electron-service 独立生命周期。与服务端一样，它要求使用 Node.js 22.23.4、24.22.1、26.12.1，或这些版本线的更高版本。将 appBinaryPath、appEntryPoint 和 appArgs 等服务选项放在 capabilities['wdio:electronServiceOptions'] 中；使用顶层的 electronRootDir 来让服务发现 Electron Builder/Electron Forge。测试项目外部的二进制文件时，将 browserVersion 设为 Electron 版本，以便服务选择兼容的 Chromedriver。

start_session({
  platform: 'electron',
  browserVersion: '33.2.1',
  capabilities: {
    'wdio:electronServiceOptions': {
      appBinaryPath: '/path/to/MyApp.app/Contents/MacOS/MyApp',
      appArgs: ['--disable-gpu']
    }
  }
})

// Privileged: this code runs in the Electron main process, not the renderer.
execute_electron_script({ script: 'return electron.app.getName()' })

现有的浏览器 DOM 工具可用于 Electron 渲染器。close_session 始终会拆除由 MCP 管理的 Electron 会话；有意不支持 detach: true。可通过 captureMainProcessLogs 或 captureRendererLogs 以及 logDir 启用主进程/渲染器日志捕获。若要触发应用深层链接，请在启动 Electron 会话时明确配置其 URI scheme。scheme 不包含冒号，且只能分发 scheme 完全匹配的 URL：

start_session({
  platform: 'electron',
  electronDeeplinkScheme: 'myapp',
  capabilities: {
    'wdio:electronServiceOptions': {
      appBinaryPath: '/path/to/MyApp.app/Contents/MacOS/MyApp'
    }
  }
})
trigger_electron_deeplink({ url: 'myapp://open/item' })

连接到正在运行的 Chrome 实例：

// First, launch Chrome with remote debugging enabled:
//
//   macOS (must quit Chrome first — open -a ignores args if Chrome is already running):
//     pkill -x "Google Chrome" && sleep 1
//     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
//       --remote-debugging-port=9222 \
//       --user-data-dir=/tmp/chrome-debug &
//
//   Linux:
//     google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
//
//   Verify it's ready: curl http://localhost:9222/json/version
start_session({attach: true})
start_session({attach: true, port: 9333})
start_session({attach: true, port: 9222, navigationUrl: 'https://app.example.com'})

连接到现有的 WebDriver 端点：

当另一个进程已接管浏览器或 WebView 的生命周期并提供 W3C WebDriver 端点时，请使用 provider: 'external'。这适用于 Selenium Grid 会话、由外部管理的浏览器驱动程序，或嵌入 WebView 并单独提供 WebDriver 的 Tauri 应用等桌面应用。MCP 服务会连接到该端点；它不会启动或停止目标应用、启动隧道，也不会管理特定框架的设置。

// Defaults to http://127.0.0.1:4445/ and browserName: 'chrome'
start_session({provider: 'external', platform: 'browser'})

// Custom WebDriver endpoint and capabilities
start_session({
    provider: 'external',
    platform: 'browser',
    webdriverConfig: {
        protocol: 'http',
        hostname: '127.0.0.1',
        port: 4445,
        path: '/'
    },
    capabilities: {
        browserName: 'tauri'
    }
})

对于 Tauri 等桌面 WebView 应用，请先在此 MCP 服务之外启动应用及其 WebDriver 桥接，然后传入端点和所需的 capabilities。例如，Tauri WebDriver 桥接可能需要 capabilities: {browserName: 'tauri'}。

连接到现有的 WebDriver 或 Appium 会话：

如果会话已由另一个进程创建，请使用 attach_session。MCP 会复用所选提供方的端点和凭据，在本地注册相应的浏览器/移动端命令集，并且不会发送新建会话请求。连接的会话由外部管理：默认情况下，close_session() 会断开连接，而 close_session({detach: false}) 会显式终止远程会话。

// Existing BrowserStack App Automate session
attach_session({
    provider: 'browserstack',
    platform: 'ios',
    sessionId: 'existing-browserstack-session-id',
    capabilities: {
        'appium:deviceName': 'iPhone 15',
        'appium:automationName': 'XCUITest'
    }
})

// Existing session on a local Appium server
attach_session({
    provider: 'local',
    platform: 'android',
    sessionId: 'existing-appium-session-id',
    appiumConfig: {
        protocol: 'http',
        host: '127.0.0.1',
        port: 4723,
        path: '/'
    }
})

// Existing mobile session on a custom W3C WebDriver endpoint
attach_session({
    provider: 'external',
    platform: 'ios',
    sessionId: 'existing-grid-session-id',
    webdriverConfig: {
        protocol: 'https',
        hostname: 'grid.example.com',
        port: 443,
        path: '/wd/hub'
    }
})

现有云会话必须继续使用创建该会话时所用的隧道。attach_session 不会启动或停止隧道，因此只要会话需要，就应让原始隧道进程保持运行。

设备仿真（需要 BiDi 会话）：

// Device emulation (requires BiDi session)
start_session({capabilities: {webSocketUrl: true}})
emulate_device()                         // list available presets
emulate_device({device: 'iPhone 15'})    // activate emulation
emulate_device({device: 'Pixel 7'})      // switch device
emulate_device({device: 'reset'})        // restore desktop defaults

Web 扩展（需要 BiDi 会话）：

start_session({platform: 'browser', browser: 'chrome', capabilities: {webSocketUrl: true}})

open_web_extension({
    extensionData: {type: 'path', path: '/path/to/unpacked-extension'},
    path: 'options.html'
})

// Drive the extension UI with the normal page tools.
get_elements()
click_element({selector: '#save'})

// For remote/cloud sessions, send a packaged extension archive as base64.
open_web_extension({
    extensionData: {type: 'base64', value: '<base64-encoded-zip>'},
    path: 'options.html'
})

移动应用自动化

在模拟器上测试 iOS 应用：

Test my iOS app located at /path/to/MyApp.app on iPhone 15 Pro simulator:
1. Start the app session
2. Tap the login button
3. Enter "testuser" in the username field
4. Take a screenshot of the home screen
5. Close the session

在会话之间保留应用状态：

Test my Android app without resetting data:
1. Start app session with noReset: true and fullReset: false
2. App launches with existing login state and user data preserved
3. Run test scenarios
4. Close session (app remains installed with data intact)

在真实设备上测试 iOS 应用：

Test my iOS app on my physical iPhone:
1. Start app session with:
   - platform: iOS
   - appPath: /path/to/MyApp.ipa
   - deviceName: My iPhone
   - udid: 00008030-001234567890ABCD (your device's UDID)
   - platformVersion: 17.0
2. Run your test scenario
3. Close the session

测试 Android 应用：

Test my Android app /path/to/app.apk on the Pixel_6_API_34 emulator:
1. Start the app with auto-grant permissions
2. Get visible elements (use inViewportOnly: false to see all elements)
3. Swipe up to scroll
4. Tap on the "Settings" button using text matching
5. Verify the settings screen is displayed

高级元素检测：

Test my app and debug layout issues:
1. Start the app session
2. Get visible elements with includeContainers: true to see the layout hierarchy
3. Analyze ViewGroup, FrameLayout, and ScrollView containers
4. Use inViewportOnly: false to find off-screen elements that need scrolling

混合应用测试（切换上下文）：

Test my hybrid app:
1. Start the Android app session
2. Tap "Open Web" button in native context
3. List available contexts
4. Switch to WEBVIEW context
5. Click the login button using CSS selector
6. Switch back to NATIVE_APP context
7. Verify we're back on the home screen

重要说明

⚠️ 会话管理：

• 同一时间只能有一个会话处于活动状态（浏览器或应用）
• 使用完毕后始终关闭会话，以释放系统资源
• 在浏览器和移动设备之间切换时，请先关闭当前会话
• 使用 close_session({ detach: true }) 可断开连接，而不终止 Appium 服务上的会话
• 创建会话时，可通过 noReset 和 fullReset 参数控制状态保留
• 使用 noReset: true 创建的会话，或未指定 appPath 创建的会话，关闭时会自动断开连接
• 使用 attach_session 接管的会话关闭时始终会断开连接，除非明确指定 detach: false

⚠️ 任务规划：

• 将复杂的自动化任务拆分为更小、更专注的操作
• 大量自动化操作可能会迅速耗尽 Claude 的消息额度

⚠️ 移动自动化：

• 启动移动会话前，必须先运行 Appium 服务
• 确保模拟器已运行且设备已连接
• iOS 自动化需要安装了 Xcode 的 macOS
• iOS 真机：在实体 iOS 设备上进行测试需要设备的 UDID（40 个字符的唯一标识符）。如何查找 UDID，请参阅 先决条件部分

选择器语法速查

Web（CSS/XPath）：

• CSS：button.my-class、#element-id
• XPath：//button[@class='my-class']
• 文本：button=Exact text、a*=Contains text

移动设备（跨平台）：

• 无障碍 ID：~loginButton（适用于 iOS 和 Android）
• Android UiAutomator：android=new UiSelector().text("Login")
• iOS 谓词：-ios predicate string:label == "Login" AND visible == 1
• XPath：//android.widget.Button[@text="Login"]

高级功能

应用状态保留

使用 noReset/fullReset 保留状态： 创建新会话时，使用 noReset 和 fullReset 参数控制应用状态：

保留状态的示例：

// Preserve login state between test runs
start_session({
    platform: 'android',
    appPath: '/path/to/app.apk',
    deviceName: 'emulator-5554',
    noReset: true,         // Don't reset app state
    fullReset: false,      // Don't uninstall
    autoGrantPermissions: true,
    capabilities: {
        'appium:chromedriverExecutable': '/path/to/chromedriver',
        'appium:autoWebview': true
    }
})
// App launches with existing user data, login tokens, preferences intact

断开会话连接： close_session 工具支持 detach 参数，可断开与会话的连接，而不终止 Appium 服务上的会话：

// Detach without killing the session
close_session({detach: true})

// Explicit session termination (closes the app and removes session)
close_session({detach: false})

使用 noReset: true 创建的会话，或未指定 appPath 创建的会话，关闭时会自动断开连接。 使用 attach_session 接管的会话由外部管理，默认也会断开连接；只有当 MCP 应有意终止现有远程会话时，才传入 detach: false。

这在以下场景中特别有用：

• 保留应用状态，以便继续手动测试
• 调试多步骤工作流（在工具调用之间让会话保持运行）
• 测试需要应用保持安装且处于当前状态的场景

智能元素检测

• 平台专属元素分类：自动识别可交互元素与布局容器
  • Android：Button、EditText、CheckBox 与 ViewGroup、FrameLayout、ScrollView
  • iOS：Button、TextField、Switch 与 View、StackView、CollectionView
• 多种定位策略：每个元素都提供无障碍 ID、资源 ID、文本、XPath 和 平台专属选择器
• 视口筛选：控制仅获取可见元素，还是获取所有元素（包括屏幕外元素）
• 布局调试：可选择包含容器元素，以了解 UI 层级结构

自动处理权限和警告

现在，iOS 和 Android 会话都支持自动处理系统权限和警告：

• autoGrantPermissions（默认值：true）：自动授予应用权限（相机、位置等）
• autoAcceptAlerts（默认值：true）：自动接受系统警告和对话框
• autoDismissAlerts（可选）：设为 true 可关闭警告，而不是接受警告

这样，在自动化测试期间就无需手动处理权限弹窗。

技术详情

• 构建技术： TypeScript、WebDriverIO、Appium
• 浏览器支持： Chrome、Firefox、Edge（有头/无头模式，自动管理驱动程序）、Safari（仅有头模式；macOS）
• 移动端支持： iOS（XCUITest）和 Android（UiAutomator2/Espresso）
• 协议： 用于集成 Claude Desktop 的 Model Context Protocol（MCP）
• 会话模型： 单个活动会话（浏览器或移动应用）
• 数据格式： TOON（面向令牌的对象表示法），用于高效的大模型通信
• 元素检测： 基于 XML 的页面源解析，结合智能筛选和多策略定位器生成

会话录制与代码导出

每次工具调用都会自动记录到会话历史中。你可以检查会话并通过 MCP 资源导出可运行代码，无需额外调用工具：

• wdio://sessions — 列出所有已录制的会话，包括类型、时间戳和步骤数
• wdio://session/current/steps — 当前活动会话的步骤日志
• wdio://session/current/code — 当前活动会话生成的可运行 WebdriverIO JS 代码
• wdio://session/{sessionId}/steps — 根据 ID 查看任意过往会话的步骤日志
• wdio://session/{sessionId}/code — 根据 ID 查看任意过往会话生成的 JS 代码

生成的脚本会将整个会话还原为独立的 import { remote } from 'webdriverio' 文件，包括 capabilities、导航、点击和输入。对于云服务提供商的会话，脚本还包含完整的 try/catch/finally，并通过服务提供商的 REST API 自动标记会话结果。

轨迹录制

向 start_session 传入 trace: true 后，会话关闭时会在 .trace/ 目录中生成兼容 Playwright 的 .trace 压缩包。可在 player.vibium.dev 播放该压缩包，并查看与操作时间线并列显示的一系列截图。

截图的时间安排

在本地模拟器上，Appium 的 takeScreenshot 往返耗时为 700–1300 ms，足以让上一步操作的动画完成。我们利用这一点：每张截图都在下一步操作执行之前捕获，因此 Appium 服务端返回的已是上一步操作完成后的稳定画面。

棘手之处在于，如何让轨迹播放器将截图显示在正确的操作下方。播放器会根据 timestamp 字段，将 screencast-frame 事件关联到时间窗口包含该时间戳的操作。如果将时间戳设为“现在”（截图捕获时间），它会早于当前操作的 startTime，播放器便会将截图标记为下一步操作的之前状态，导致操作错位一步。

解决方法：将每个 screencast-frame 的时间戳设为 lastAfterEndTime，也就是刚完成操作的 endTime。这样，截图就会落在上一步操作的时间窗口内，播放器会将其显示为该操作的结果，而不是下一步操作的前置画面。

Timeline (monotonic ms):

  prev.endTime ← frame timestamp stamped here
        │
        │   [screenshot captured here — shows settled state after prev action]
        │
  curr.startTime
        │
        │   [action executes]
        │
  curr.endTime ← next frame will be stamped here

会话关闭时的最终截图会使用最后一步操作的 endTime 作为时间戳，因此它会显示在该操作下方，而不会在时间线结束后作为孤立画面出现。

会话日志

wdio://session/current/logs 资源会返回当前会话的崩溃报告、控制台错误和系统日志，并自动检测会话类型以获取相应的日志缓冲区：

注意：读取此资源会清空日志缓冲区（根据 WebDriver 规范）。之后读取的内容只包含自上次读取以来累积的条目。浏览器日志需要 Chromium（Chrome/Edge）——Firefox 和 Safari 不支持 getLogs 命令。

响应为 JSON，包含 sessionType、logTypes（可用日志类型）和 entries；每个条目包含 level、message、timestamp（Unix 毫秒）和 timestampISO。

故障排除

浏览器自动化无法运行？

• 确保已安装 Chrome、Firefox、Edge 或 Safari（Safari 需要 macOS）
• 尝试彻底重启 Claude Desktop
• 检查是否有其他 WebDriver 实例正在运行

移动端自动化无法运行？

• 确认 Appium 服务正在运行：appium
• 检查设备/模拟器是否正在运行：adb devices（Android）或 Xcode Devices（iOS）
• 确保已安装正确的平台驱动
• 确认应用路径正确且可访问

**发现问题或有建议？**欢迎分享反馈！