适合谁
- 使用 Appium 进行 Android/iOS 自动化测试的团队
- 希望用自然语言创建与调试移动测试的开发者
- 需要生成测试代码与 Page Object 模板的工程团队
- 在受信任 CI 环境中运行移动自动化的团队
M
57FMRS · C
MCP Appium 是 Appium 组织维护的 MCP 服务器，把 Appium 的移动自动化能力以工具形式暴露给 AI 助手，覆盖 Android 与 iOS 的模拟器、仿真器和真机，具备元素查找、手势操作、会话管理、测试代码生成、插件机制与 OpenTelemetry 追踪等较完整的功能。它面向使用 Appium 的移动测试团队，安装与配置以 stdio 与 npx 为主，通过环境变量控制能力开关。需要注意的边界是：它被设计为本地单用户或受信任 CI 组件，不适合作为面向不受信任客户端的共享服务，且远程服务器地址、视觉模型调用与会话清理策略都需要显式配置。
MCP Appium 是一个基于 Model Context Protocol 的服务器，为 AI 助手提供移动自动化工具集，覆盖 Android（UiAutomator2）与 iOS（XCUITest），支持模拟器、仿真器与真机。它支持自然语言元素查找、智能定位器生成、会话管理、手势操作与自动生成 Java/TestNG 测试代码，并提供 Page Object Model 模板。服务器可通过 npx appium-mcp@latest 以 stdio 方式启动，内置 UiAutomator2 与 XCUITest 驱动包，也可通过 remoteServerUrl 连接远程 Appium/WebDriver 服务器。项目由 Appium 组织维护，采用 Apache-2.0 许可证。
工具能力
select_device
必需的第一步：发现可用设备并选择其一，仅有一台设备时自动选择。
prepare_ios_simulator
一次调用完成启动 iOS/tvOS 模拟器、下载 WebDriverAgent（若未缓存）并安装启动 WDA。
appium_prepare_ios_real_device
准备真机 iOS 设备：先列出可用 .mobileprovision 描述文件，再按所选 UUID 下载 WDA、打包为 IPA 并重签名。
appium_session_management
统一会话管理：create、attach、detach、delete、list、select。
appium_mobile_device_control
控制设备行为：锁屏/解锁、摇动设备、打开通知面板。
appium_driver_settings
读取或更新 Appium 驱动会话设置。
appium_context
管理上下文：列出所有上下文（含原生与 WebView）或在上下文之间切换。
appium_find_element
使用传统定位策略查找元素，优先级为 accessibility id、id、平台原生策略，最后才用 xpath。
appium_ai
可选（需 AI_VISION_ENABLED=true）：基于视觉模型的自然语言元素查找，返回可供手势工具使用的坐标标识。
appium_gesture
执行触摸手势：返回、点击、双击、长按、滚动、滑动、缩放以及滚动直到元素出现。
appium_drag_and_drop
执行拖放手势，支持元素与坐标之间的组合。
appium_perform_actions
执行原始 W3C Actions API 序列，用于自定义多点触控手势。
appium_set_value
向输入框输入文本。
appium_screenshot
截取设备屏幕。
appium_get_page_source
获取当前页面源代码。
generate_locators
生成元素定位器。
appium_screen_recording
开始或停止屏幕录制，输出 MP4 文件。
appium_app_lifecycle
管理应用生命周期，包括列出应用。
appium_documentation_query
对 Appium 文档进行 RAG 检索（需启用且安装可选包）。
appium_skills
Appium 技能相关文档工具（需启用且安装可选包）。
安装接入
- 确保系统安装 Node.js v22 或更高版本、npm 或 yarn、JDK 8 或更高版本；Android 测试需 Android SDK 并设置 ANDROID_HOME，iOS 测试需 macOS 上的 Xcode。
- 在 MCP 客户端配置中添加服务器：command 为 npx，args 为 ["appium-mcp@latest"]，type 为 stdio，并在 env 中设置 ANDROID_HOME。
- 可选：创建 capabilities.json 并通过 CAPABILITIES_CONFIG 环境变量指向它，或用 Cursor 的一键安装按钮、gemini mcp add appium-mcp npx -y appium-mcp@latest、claude mcp add appium-mcp -- npx -y appium-mcp@latest 进行安装。
- 先调用 select_device 选择设备，再创建会话开展自动化。
claude_desktop_config.json
{
"mcpServers": {
"appium-mcp": {
"disabled": false,
"timeout": 100,
"type": "stdio",
"command": "npx",
"args": ["appium-mcp@latest"],
"env": {
"ANDROID_HOME": "/path/to/android/sdk",
"CAPABILITIES_CONFIG": "/path/to/your/capabilities.json"
}
}
}
}
选型与风险
不适合谁
- 面向不受信任用户的共享或多租户服务场景
- 没有 Android SDK、Xcode 或 Java 工具链的环境
- 需要纯浏览器或桌面端网页自动化而非移动端的场景
所需权限
- 读取本机 Android SDK 与 Xcode/模拟器环境
- 通过 adb 或模拟器访问本地移动设备或仿真器
- 读写截图与录屏目录（SCREENSHOTS_DIR 或系统临时目录）
- 可选：访问远程 Appium/WebDriver 服务器（remoteServerUrl）
- 可选：调用外部视觉模型 API（AI_VISION_API_BASE_URL 与 AI_VISION_API_KEY）
风险与副作用
- remoteServerUrl 由调用方控制，若由不受信任输入构造可能连接到非预期的服务器，可用 REMOTE_SERVER_URL_ALLOW_REGEX 限制目标地址
- 默认在 MCP 客户端断开时删除所有 MCP 拥有的 Appium 会话，使用 httpStream 等易断开的传输可能一次性清空自动化会话，可用 APPIUM_MCP_ON_CLIENT_DISCONNECT=skip 保留
- 启用视觉查找会把截图发送给第三方视觉模型 API，可能产生费用与数据外泄风险
- 会话持久化文件可能包含凭据与敏感 capabilities（以 0600 权限创建）
- 插件在服务器进程内执行，只能加载受信任的文件与包
常见排障
- 服务器启动失败并提示缺少 AI_VISION_API_BASE_URL 或 AI_VISION_API_KEY：说明设置了 AI_VISION_ENABLED=true 但未配置这两个变量
- 找不到 appium_ai 工具：确认 AI_VISION_ENABLED 已设为 true
- 找不到文档工具：确认已安装 @appium/mcp-documentation 且 APPIUM_MCP_DOCS_ENABLED 为 true
- 连接远程服务器被拒：检查 REMOTE_SERVER_URL_ALLOW_REGEX 是否匹配，以及 URL 是否包含查询字符串或片段
- 会话在客户端重连后消失：将 APPIUM_MCP_ON_CLIENT_DISCONNECT 设为 skip
- iOS 屏幕录制失败：确认 ffmpeg 已安装并在 PATH 中
- 响应过大或过慢：设置 NO_UI=true 或 NO_UI=1
使用场景
让 AI 助手用自然语言驱动 Android 或 iOS 应用进行自动化测试
根据自然语言描述自动生成 Java/TestNG 测试代码
在 CI 中以 NO_UI 模式批量执行移动端自动化以节省 token 与带宽
为难以用传统定位器识别的界面元素启用视觉模型查找
通过 appium_documentation_query 查询 Appium 官方文档
支持客户端
Cursor完整支持
Claude Code完整支持
Gemini CLI完整支持