MCP Appium

官方

面向 iOS 与 Android 的 Appium 移动自动化 MCP 服务器

分类: 开发工具第 158 / 438
Stars: ★ 512 非常热门
传输方式: stdio（本地进程）
运行环境: Node.js 22+ · Java 8+ · 预编译二进制 Android SDK (adb) fo
凭据: 可选 API Key
许可证: Apache-2.0
最近提交: 1 天前
工具数: 20

57FMRS · C

MCP Appium 是 Appium 组织维护的 MCP 服务器，把 Appium 的移动自动化能力以工具形式暴露给 AI 助手，覆盖 Android 与 iOS 的模拟器、仿真器和真机，具备元素查找、手势操作、会话管理、测试代码生成、插件机制与 OpenTelemetry 追踪等较完整的功能。它面向使用 Appium 的移动测试团队，安装与配置以 stdio 与 npx 为主，通过环境变量控制能力开关。需要注意的边界是：它被设计为本地单用户或受信任 CI 组件，不适合作为面向不受信任客户端的共享服务，且远程服务器地址、视觉模型调用与会话清理策略都需要显式配置。

最强项 · 文档质量 14/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

12/20

维护活跃度

11/20

文档质量

14/20

安装易用性

11/20

查看各项评分依据

可靠性 9/20: 静态审查仅能看到 README 与 server.json：清单包名、版本(1.94.0)与 npm 标识一致，stdio 传输声明明确，README 描述了会话生命周期、断开清理策略(delete_all/skip)与错误码归一化等可诊断行为。但仓库未提供任何可见的 CI 工作流、提交的测试文件或可复现日志证据，工具清单表格在文档中被截断，无法核对声明工具与实际注册是否一致；因此可靠性按静态校准上限以下取值，扣分主要来自缺少可验证执行证据与边界/错误处理实证。
安全与权限 12/20: 未触及红线：无恶意代码、凭据外传或默认破坏性远程命令。README 显出较好的安全自觉——AI 视觉与文档工具默认关闭并按环境变量门控，remoteServerUrl 支持 REMOTE_SERVER_URL_ALLOW_REGEX 白名单、拒绝 query/fragment、附加会话不做 HTTP 重定向跟随、URL userinfo 日志脱敏、持久化会话文件 0600 权限。但默认行为仍偏宽松：未设正则时接受任意 HTTP(S) 目标，客户端断开默认删除全部 MCP 拥有的 Appium 会话，是缺少确认的潜在破坏性副作用；远程 URL 与 capabilities 可由工具参数注入，缺少强制确认步骤；无沙箱或权限最小化的进程级约束。综合扣分至中等水平。
维护活跃度 11/20: Apache-2.0 许可明确，版本号 1.94.0 与高版本迭代暗示持续发布，477 stars、23 open issues、未归档为活跃信号（仅作发现信号，未加分）。依赖栈包含 appium-uiautomator2-driver、appium-xcuitest-driver、FastMCP 等，README 对 OpenTelemetry、插件 API、可选文档包做了版本化说明，体现一定治理意识。但静态材料中看不到提交历史、发布节奏、依赖更新策略、安全响应渠道或明确维护者归属，缺少可核验的维护证据，故按中等偏上但非满值评分。
文档质量 14/20: 文档覆盖面明显较全：安装(含 Cursor 一键、Gemini CLI、Claude Code)、环境变量全表、capabilities 示例、平台 general 模式、多会话与 sessionId、断开清理权衡、屏幕录制、AI 视觉模型基准与坐标处理、NO_UI/MCP Apps 性能权衡、插件 API 与生命周期、远程服务器信任模型与正则白名单示例。示例中未出现真实 token/密钥。扣分点在于工具表格在给定材料中被截断、部分参数与返回结构缺少完整示例、故障排查章节偏薄，且展示的 100% 准确率等基准数据在静态审查中无法独立验证。
安装易用性 11/20: 安装路径清晰：Node 22+、JDK、Android SDK、Xcode 前置条件明确，npx appium-mcp@latest 的 stdio 配置示例在主流客户端可复用，并提供 Cursor 深链、Gemini CLI 与 Claude Code CLI 命令。但真实可用仍依赖本地 Android SDK/ANDROID_HOME、Xcode 与设备签名、iOS 真机 provisioning profile、ffmpeg 等较重环境准备，属于手动且易碎；平台 general 模式强制要求 remoteServerUrl。缺乏端到端可复现的集成示例与常见失败排查步骤，故按静态校准上限以下给分。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么执行命令或代码访问网络控制浏览器

适合谁

使用 Appium 进行 Android/iOS 自动化测试的团队
希望用自然语言创建与调试移动测试的开发者
需要生成测试代码与 Page Object 模板的工程团队
在受信任 CI 环境中运行移动自动化的团队

不适合谁

面向不受信任用户的共享或多租户服务场景
没有 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 权限创建）
插件在服务器进程内执行，只能加载受信任的文件与包

安装接入

准备工作

运行环境：Node.js 22+ · Java 8+ · 预编译二进制 Android SDK (adb) fo

AI_VISION_API_KEY 可选密钥视觉模型服务商的 API 密钥，启用 AI_VISION_ENABLED 时必填，需保密。

其他可选配置项（24 个）

ANDROID_HOME 可选 Android SDK 安装路径（如 /Users/xyz/Library/Android/sdk），Android 测试必需。

CAPABILITIES_CONFIG 可选指向 capabilities. 的绝对路径，用于按平台预设设备能力，可选。

SCREENSHOTS_DIR 可选截图和录屏文件保存目录，默认系统临时目录，可选。

NO_UI 可选设为 true/1 关闭 HTML UI 组件，加快响应并节省 token，可选。

APPIUM_MCP_APPS_ENABLED 可选设为 false/0 强制使用内嵌 UI 兼容模式，默认开启 MCP Apps 静态 UI，可选。

APPIUM_MCP_ON_CLIENT_DISCONNECT 可选客户端断开时的会话清理策略：delete_all（默认）或 skip，可选。

APPIUM_MCP_WDA_APP_PATH 可选本地 WebDriverAgent-Runner.app 包路径，跳过 GitHub 下载，可选。

REMOTE_SERVER_URL_ALLOW_REGEX 可选限制可连接的远程 Appium 服务器 URL 的正则表达式，可选。

AI_VISION_ENABLED 可选设为 true 启用 appium_ai 视觉找元素工具，可选，默认关闭。

AI_VISION_API_BASE_URL 可选 OpenAI 兼容视觉模型 API 的基础 URL，启用 AI_VISION_ENABLED 时必填。

AI_VISION_MODEL 可选视觉模型名称，默认 Qwen3-VL-235B-A22B-Instruct，可选。

AI_VISION_COORD_TYPE 可选坐标类型：normalized（默认）或 absolute，可选。

AI_VISION_IMAGE_MAX_WIDTH 可选发送给视觉 API 前图片最大宽度，默认 1080，可选。

AI_VISION_IMAGE_QUALITY 可选压缩截图的 JPEG 质量 1-100，默认 80，可选。

APPIUM_MCP_DOCS_ENABLED 可选设为 true 启用文档查询工具，需额外安装 @appium/mcp-documentation 包，可选。

SENTENCE_TRANSFORMERS_MODEL 可选文档语义搜索用的 Hugging Face 模型，默认 Xenova/all-MiniLM-L6-v2，可选。

APPIUM_MCP_PERSIST_REMOTE_SESSIONS_PATH 可选持久化已附加远程会话信息的目录路径，可选。

APPIUM_MCP_EVIDENCE 可选设为 true/1 时在工具响应中附加结构化操作证据记录，用于 CI/调试，可选。

APPIUM_MCP_OTEL_ENABLED 可选设为 true 启用 OpenTelemetry 追踪，默认关闭，可选。

APPIUM_MCP_OTEL_INCLUDE_ARGUMENT_VALUES 可选设为 true 在 span 中包含脱敏后的参数值，默认关闭，可选。

OTEL_SERVICE_NAME 可选上报给 OpenTelemetry 收集器的服务名，如 appium-mcp，可选。

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 可选 OTLP/HTTP 追踪上报端点，如 http://127.0.0.1:4318/v1/traces，可选。

OTEL_TRACES_SAMPLER 可选追踪采样策略，如 parentbased_always_on，可选。

OTEL_RESOURCE_ATTRIBUTES 可选附加到每个 span 的逗号分隔 key=value 资源属性，可选。

确保系统安装 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 选择设备，再创建会话开展自动化。

.cursor/mcp.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"
      }
    }
  }
}

以 Cursor 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "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"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add appium-mcp -e ANDROID_HOME=/path/to/android/sdk -e CAPABILITIES_CONFIG=/path/to/your/capabilities.json -- npx appium-mcp@latest

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端工具列表中应看到 select_device 和 appium_session_management 等工具；让 AI 调用 select_device 列出设备，能返回设备列表即说明连接成功。

常见排障

服务器启动失败并提示缺少 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 设备并选中它。
在这台 iPhone 模拟器上启动我的应用，然后给屏幕截图。
向下滚动页面直到看到登录按钮，然后点击它。
录一段 Android 设备屏幕的操作视频，结束后告诉我文件路径。

工具能力 20

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。

展开其余 12 个工具

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 技能相关文档工具（需启用且安装可选包）。

使用场景

让 AI 助手用自然语言驱动 Android 或 iOS 应用进行自动化测试

根据自然语言描述自动生成 Java/TestNG 测试代码

在 CI 中以 NO_UI 模式批量执行移动端自动化以节省 token 与带宽

为难以用传统定位器识别的界面元素启用视觉模型查找

通过 appium_documentation_query 查询 Appium 官方文档

支持客户端

Cursor

Claude Code

Gemini CLI

依据项目文档列出，未经本站实测。

详细介绍

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 许可证。