JinDaGe - appium-mcp MCP Details

article

README

🚀 MCP Appium - 用于移动开发与自动化的 MCP 服务器 | 支持 iOS、安卓、模拟器、仿真器和真机

MCP Appium 是一款智能的 MCP（模型上下文协议）服务器，旨在为 AI 助手提供一套强大的移动自动化工具。它通过支持自然语言交互、智能定位器生成以及为安卓和 iOS 平台自动创建测试，简化了移动应用测试流程。

🚀 快速开始

MCP Appium 为移动自动化测试带来了诸多便利，你可以按照以下步骤快速开启使用之旅。请先确保满足先决条件，这是顺利使用的基础。接着，根据你的使用场景，选择合适的安装方式，如在 Cursor IDE、使用 Gemini CLI 或 Claude Code CLI 等。安装完成后，还需要进行配置，包括设置设备能力和截图保存位置等。最后，你可以参考使用示例，开展自动化测试工作。

✨ 主要特性

跨平台支持：可对安卓（UiAutomator2）和 iOS（XCUITest）平台进行自动化测试。
智能定位器生成：借助基于优先级的策略，利用 AI 实现元素识别。
交互式会话管理：轻松在本地移动设备上创建和管理会话。
智能元素交互：能够执行点击、文本输入、截图和查找元素等操作。
自动化测试生成：根据自然语言描述生成 Java/TestNG 测试代码。
支持页面对象模型：使用遵循行业最佳实践的内置模板。
灵活配置：可针对不同环境自定义功能和设置。

📦 安装指南

标准配置

标准配置适用于大多数工具：

{
  "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 IDE 中安装

在 Cursor IDE 中安装 MCP Appium 最简单的方法是使用一键安装按钮：这将自动在你的 Cursor IDE 设置中配置 MCP 服务器。请确保在配置中更新 ANDROID_HOME 环境变量，使其与你的安卓 SDK 路径匹配。

或手动安装

前往 Cursor 设置 → MCP → 添加新的 MCP 服务器。为其命名，使用命令类型并输入命令 npx -y appium-mcp@latest。你还可以通过点击编辑来验证配置或添加命令参数。

以下是推荐的配置：

{
  "appium-mcp": {
    "disabled": false,
    "timeout": 100,
    "type": "stdio",
    "command": "npx",
    "args": ["appium-mcp@latest"],
    "env": {
      "ANDROID_HOME": "/Users/xyz/Library/Android/sdk"
    }
  }
}

注意：请确保更新 ANDROID_HOME 路径，使其与你的安卓 SDK 安装路径匹配。

使用 Gemini CLI 安装

使用 Gemini CLI 添加 MCP Appium 服务器：

gemini mcp add appium-mcp npx -y appium-mcp@latest

这将自动配置 MCP 服务器以供 Gemini 使用。请确保在配置中更新 ANDROID_HOME 环境变量，使其与你的安卓 SDK 路径匹配。

使用 Claude Code CLI 安装

使用 Claude Code CLI 添加 MCP Appium 服务器：

claude mcp add appium-mcp -- npx -y appium-mcp@latest

这将自动配置 MCP 服务器以供 Claude Code 使用。请确保在配置中更新 ANDROID_HOME 环境变量，使其与你的安卓 SDK 路径匹配。

⚙️ 配置

设备能力

创建一个 capabilities.json 文件来定义你的设备能力：

{
  "android": {
    "appium:app": "/path/to/your/android/app.apk",
    "appium:deviceName": "Android Device",
    "appium:platformVersion": "11.0",
    "appium:automationName": "UiAutomator2",
    "appium:udid": "your-device-udid"
  },
  "ios": {
    "appium:app": "/path/to/your/ios/app.ipa",
    "appium:deviceName": "iPhone 15 Pro",
    "appium:platformVersion": "17.0",
    "appium:automationName": "XCUITest",
    "appium:udid": "your-device-udid"
  }
}

设置 CAPABILITIES_CONFIG 环境变量，使其指向你的配置文件。

截图设置

设置 SCREENSHOTS_DIR 环境变量来指定截图的保存位置。如果未设置，截图将保存到当前工作目录。支持绝对路径和相对路径（相对路径相对于当前工作目录解析）。如果目录不存在，将自动创建。

🎯 可用工具

MCP Appium 提供了一套全面的工具，分为以下几类：

平台与设备设置

| 工具 | 描述 | | ----------------- | ---------------------------------------------------------------- | | select_platform | 首次使用必需：询问用户选择安卓或 iOS 平台 | | select_device | 当有多个设备可用时，选择特定的设备 | | boot_simulator | 启动 iOS 模拟器并等待其就绪（仅适用于 iOS） | | setup_wda | 为 iOS 模拟器下载并设置预构建的 WebDriverAgent（仅适用于 iOS） | | install_wda | 在已启动的 iOS 模拟器上安装并启动 WebDriverAgent（仅适用于 iOS） |

会话管理

| 工具 | 描述 | | ---------------- | --------------------------------------------------- | | create_session | 为安卓或 iOS 创建新的移动自动化会话 | | delete_session | 删除当前的移动会话并清理资源 |

上下文管理

| 工具 | 描述 | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | appium_get_contexts | 获取当前 Appium 会话中所有可用的上下文。返回上下文名称列表，包括 NATIVE_APP 和任何 Web 视图上下文（例如，WEBVIEW_ 或 WEBVIEW_）。 | | appium_switch_context | 切换到 Appium 会话中的特定上下文。用于在原生应用上下文（NATIVE_APP）和 Web 视图上下文（WEBVIEW_ 或 WEBVIEW_）之间切换。请先使用 appium_get_contexts 查看可用上下文。 |

元素发现与交互

| 工具 | 描述 | | --------------------- | ------------------------------------------------------------------------------------- | | appium_find_element | 使用各种定位策略（xpath、id、可访问性 id 等）查找特定元素 | | appium_click | 点击元素 | | appium_double_tap | 对元素执行双击操作 | | appium_long_press | 对元素执行长按（按下并保持）手势 | | appium_drag_and_drop | 执行从源位置到目标位置的拖放手势（支持元素到元素、元素到坐标、坐标到元素和坐标到坐标） | | appium_set_value | 在输入字段中输入文本 | | appium_get_text | 获取元素的文本内容 |

屏幕与导航

| 工具 | 描述 | | -------------------------- | ------------------------------------------------ | | appium_screenshot | 对当前屏幕进行截图并保存为 PNG 格式 | | appium_scroll | 垂直滚动屏幕（向上或向下） | | appium_scroll_to_element | 滚动屏幕直到特定元素可见 | | appium_swipe | 按方向（左、右、上、下）或在自定义坐标之间滑动屏幕 | | appium_get_page_source | 获取当前屏幕的页面源（XML） |

应用管理

| 工具 | 描述 | | --------------------- | ----------------------------------------------------------- | | appium_activate_app | 通过包 ID 激活（启动/置于前台）指定的应用 | | appium_installApp | 从文件路径在设备上安装应用 | | appium_uninstallApp | 通过包 ID 从设备上卸载应用 | | appium_terminateApp | 终止（关闭）指定的应用 | | appium_list_apps | 列出设备上所有已安装的应用（仅适用于安卓） |

测试生成与文档查询

| 工具 | 描述 | | ---------------------------- | -------------------------------------------------------------------------- | | generate_locators | 为当前屏幕上的所有交互式元素生成智能定位器 | | appium_generate_tests | 根据自然语言场景生成自动化测试代码 | | appium_documentation_query | 使用 RAG 查询 Appium 文档以获取帮助和指导 |

🤖 客户端支持

MCP Appium 设计为与任何符合 MCP 标准的客户端兼容。

💻 使用示例

亚马逊移动应用结账流程

以下是一个测试亚马逊移动应用结账流程的示例提示：

打开亚马逊移动应用，搜索“iPhone 15 Pro”，选择第一个搜索结果，将商品添加到购物车，进入结账流程，使用电子邮件“test@example.com”和密码“testpassword123”登录，选择送货地址，选择付款方式，查看订单详情，然后下单。使用 JAVA + TestNG 生成测试。

此示例展示了一个完整的电子商务结账流程，可使用 MCP Appium 的智能定位器生成和测试创建功能实现自动化。

🙌 贡献

欢迎贡献代码！请随时提交拉取请求或开启问题讨论任何更改。

📄 许可证

本项目采用 Apache-2.0 许可证。详情请参阅 LICENSE 文件。

appium-mcp