@gavrix/appium-mcp

这是一个基于Appium的MCP（模型-上下文-协议）服务器，它提供了对iOS模拟器和Android模拟器/设备的移动自动化功能，作为MCP客户端的工具。该服务器使标准化控制和与移动设备交互成为可能。

此服务器充当桥梁，允许MCP客户端（如大型语言模型或自动化脚本）通过Appium与移动应用程序进行交互。

概述

该项目的主要目标是通过模型上下文协议提供一组可调用的工具。这些工具抽象了Appium用于移动应用测试和自动化的功能。

服务器支持iOS模拟器和Android模拟器/设备，并具有自动设备检测和平台特定优化功能。

为了便于使用，服务器设计为通过npx运行。

安装

要在项目中将此服务器作为依赖项使用（尽管通常通过npx独立运行）：

npm install @gavrix/appium-mcp

或者，如果您使用Yarn：

yarn add @gavrix/appium-mcp

使用

最常见的运行服务器方式是使用npx：

npx @gavrix/appium-mcp

这将启动MCP服务器，然后监听来自MCP客户端（例如通过stdio）的传入连接。

对于MCP客户端配置

如果您正在配置一个MCP客户端（如Cursor）以使用此服务器，您通常会设置如下命令（假设包已全局安装或使用npx）：

{
  "command": "npx",
  "args": ["@gavrix/appium-mcp"],
  "env": {}
}

可用工具

服务器向MCP客户端暴露以下工具：

会话管理

• start_session: 启动一个Appium会话，自动检测设备（iOS模拟器或Android模拟器/设备）。支持平台选择和设备定位。
  • 参数：platform（可选）：'ios'、'android' 或 'auto'（默认）
  • 参数：deviceName（可选）：要定位的具体设备名称
• end_session: 结束当前Appium会话并清理资源。

应用控制

• launch_app: 使用其标识符（iOS的包ID，Android的包名）启动应用程序。

元素交互

• find_element: 使用指定策略和选择器在当前屏幕上查找UI元素。
• tap_element: 点击或点击由其唯一元素ID识别的元素。
• enter_text: 在特定元素（如输入字段）中输入文本。
• get_element_text: 获取元素中的文本内容。

屏幕捕获与分析

• get_page_source: 获取当前屏幕的XML源层次结构。
• get_page_source_file: 将页面源XML保存到指定文件路径。
• get_screenshot: 捕获屏幕截图并将其作为base64编码的数据返回。
• get_screenshot_file: 捕获屏幕截图并将其保存到指定文件路径。

设备交互

• simulate_gesture: 使用W3C WebDriver Actions API模拟自定义手势，使用归一化坐标（0.0-1.0）。
• press_home_button: 模拟按下主页按钮，将应用程序发送到后台（iOS和Android）。
• get_device_logs: 从连接的设备/模拟器获取控制台日志。

平台特定功能

iOS支持：

• 自动检测已启动的iOS模拟器
• 使用xcrun simctl捕获iOS特定的日志
• 支持iOS特定的元素查找策略（-ios class chain，-ios predicate string）

Android支持：

• 自动检测连接的Android设备和模拟器
• Android logcat捕获
• 支持Android特定的元素查找策略（-android uiautomator）

请参阅MCP客户端内的工具定义或服务器源代码（tools/目录）以获取每个工具的详细模式和描述。

前提条件

对于iOS支持

• 安装了Xcode和Xcode命令行工具的macOS
• 运行中的iOS模拟器
• 在端口4723上运行的Appium服务器

对于Android支持

• 已安装并在PATH中可用的Android SDK和ADB
• 运行中的Android模拟器或连接的物理设备
• 在端口44723上运行的Appium服务器

贡献

欢迎贡献、问题报告和功能请求！ 请随意查看问题页面。

许可证

此项目采用ISC许可证。

作者：Sergey Gavrilyuk sergey.gavrilyuk@gmail.com