WebDriverIO MCP 服务器使用指南

项目简介

WebDriverIO MCP 服务器是一个功能强大的自动化测试工具，通过 Model Context Protocol (MCP) 为 Claude Desktop 提供完整的 Web 和移动应用自动化能力。

主要功能

浏览器自动化

会话管理：启动和关闭 Chrome 浏览器（支持无头/有头模式）
页面交互：导航网址、点击元素、填写表单、获取内容
页面分析：获取可见元素、无障碍访问树、截图
Cookie 管理：获取、设置和删除 cookies
滚动控制：可配置像素距离的平滑滚动

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

原生应用测试：通过 Appium 测试 iOS (.app/.ipa) 和 Android (.apk) 应用
触摸手势：点击、滑动、长按、拖拽
应用生命周期：启动、后台运行、终止、检查应用状态
上下文切换：在原生应用和 WebView 之间无缝切换
设备控制：旋转、锁定/解锁、GPS 定位、键盘控制、通知面板

跨平台元素定位

Web：CSS 选择器、XPath
移动端：无障碍 ID、UiAutomator (Android)、Predicate (iOS)

安装步骤

前提条件

浏览器自动化：

Node.js（版本 18 或更高）
Claude Desktop 应用
Chrome 浏览器（WebDriverIO 自动管理）

移动应用自动化（可选）：

全局安装 Appium：'npm install -g appium'
平台驱动：
- iOS：'appium driver install xcuitest'（需要 macOS 上的 Xcode）
Android：'appium driver install uiautomator2'（需要 Android Studio）
设备/模拟器：
- iOS 模拟器（macOS）或物理设备
- Android 模拟器或物理设备

配置 Claude Desktop

在 Claude Desktop 的 MCP 设置中添加以下配置：

{
  "mcpServers": {
    "webdriverio-mcp": {
      "command": "npx",
      "args": ["-y", "webdriverio-mcp"]
  }
}

重启 Claude Desktop

⚠️ 重要提示：您可能需要完全重启 Claude Desktop。在 Windows 上，使用任务管理器确保它完全关闭后重新启动。

移动自动化设置（可选）

启动 Appium 服务器：

appium
# 服务器默认运行在 http://127.0.0.1:4723

## 基本使用方法

### 浏览器自动化示例

启动 Chrome 浏览器，导航到示例网站并测试：

启动浏览器（可选择无头模式）
获取可见元素
点击按钮或填写表单
获取元素文本或截图


### 移动应用测试示例

测试 Android 应用：

启动应用会话（支持权限自动授予）
获取可见元素（支持视口过滤和容器包含）
点击"跳过"按钮绕过引导页
验证主屏幕加载
截图记录结果


## 重要注意事项

⚠️ **会话管理**：
- 一次只能有一个活跃会话（浏览器或移动应用）
- 完成后务必关闭会话以释放系统资源
- 要在浏览器和移动端之间切换，请先关闭当前会话

### 状态保持功能
通过 'noReset' 和 'fullReset' 参数控制应用状态：

| noReset | fullReset | 行为                         |
|---------|-----------|------------------------------|
| 'true'  | 'false'   | 保持状态：应用保持安装，数据保留 |

### 会话分离模式
使用 'close_session({ detach: true })' 在不终止 Appium 服务器上的会话的情况下断开连接。

**此功能特别适用于**：
- 保持应用状态以进行手动测试延续
- 调试多步骤工作流程

## 故障排除

**浏览器自动化不工作？**
- 确保 Chrome 已安装
- 尝试完全重启 Claude Desktop
- 检查没有其他 WebDriver 实例在运行

关键词