使用说明

Appium MCP服务器

一种模型上下文协议（MCP）服务器，为移动自动化提供MCP客户端和Appium之间的无缝集成。此服务器支持与移动设备和模拟器的自然语言交互，用于自动测试、移动应用程序测试和设备控制。

特性

自然语言界面：使用对话命令控制移动设备
完整的移动自动化：涵盖Appium基本操作的全面工具
跨平台支持：iOS和Android设备、模拟器和仿真器
AI优化发现：用于移动应用分析和测试生成的专用工具
灵活的工具控制：使用环境变量限制可用工具
TypeScript实现：完全类型安全和更好的错误处理

🚀 第5阶段：平台特定增强

最新版本为iOS和Android引入了高级平台特定功能，为每个平台提供了更深入的集成和优化的性能：

iOS特定功能

模拟器管理：以编程方式创建、启动、重置和管理iOS模拟器
谓词定位器：使用NSredicate字符串进行高级iOS元素选择
类链定位器：利用iOS类链选择器处理复杂的元素层次结构
系统警报：自动处理iOS系统警报和权限
自然式滚动：iOS优化的滑动手势，具有动量和自然感

Android特定功能

仿真器管理：使用高级配置选项控制Android模拟器
UiAutomator定位器：将UiAutomator选择器用于Android特定的元素位置
DataMatcher定位器：使用DataMatcher模式进行高级Android元素定位
权限管理：动态授予和撤销Android应用程序权限
网络控制：以编程方式切换WiFi、移动数据和飞行模式

跨平台能力

智能定位器路由：自动为每个平台选择最佳定位器策略
增强手势：具有平台感知的手势系统，支持iOS和Android
后备策略：如果主要方法失败，请尝试多种定位器方法
平台检测：具有优化默认值的自动平台检测
统一API：单一界面，无缝适应iOS或Android

高级功能

定位器建议：获取特定平台的定位器策略建议
元素验证：全面的元素状态检查（可见、启用、可点击）
性能优化：针对平台的优化，以实现更快的元素定位
类型安全：完全支持TypeScript，具有严格的类型检查

先决条件

Node.js 18.0.0或更高版本
TypeScript 5.0.0或更高版本
Appium服务器2.0+
移动开发环境：
- 安卓：安卓SDK、UiAutor2驱动程序、安卓设备/模拟器
- iOS：Xcode、XCUITest驱动程序、iOS模拟器（仅限macOS）

安装

克隆项目

git clone https://github.com/agbobli5373/appium-mcp-server.git
cd appium-mcp-server

安装依赖项

使用pnpm

pnpm install

使用纱线

yarn install

构建项目

使用pnpm

pnpm build

使用纱线

yarn build

测试服务器（可选）

node dist/index.js

您应该看到： Appium MCP Server running on stdio

使用示例

直接启动包装器（用于本地测试）

# bash
node wrapper.cjs
# You should see: Appium MCP Server running on stdio

使用有限的工具集启动包装器

# bash
export MCP_TOOLS='["start_session","find_mobile_element","tap_element"]'
node wrapper.cjs

MCP客户端-服务器配置示例（Windows）

{
    "servers": {
        "appium": {
            "command": "node",
            "args": ["C:\\absolute\\path\\to\\appium-mcp-server\\wrapper.cjs"]
        }
    }
}

MCP客户端集成

工具调用示例

启动Appium会话

{
    "tool": "start_session",
    "args": {
        "platformName": "Android",
        "platformVersion": "12.0",
        "deviceName": "emulator-5554",
        "automationName": "UiAutomator2"
    }
}

查找并点击元素

{
    "tool": "find_mobile_element",
    "args": {
        "by": "accessibility-id",
        "value": "login-button"
    }
}

{
    "tool": "tap_element",
    "args": {
        "by": "accessibility-id",
        "value": "login-button"
    }
}

执行滑动手势

{
    "tool": "swipe_screen",
    "args": {
        "direction": "up",
        "distance": 0.5
    }
}

第5阶段：高级平台特定示例

iOS模拟器管理

{
    "tool": "ios_create_simulator",
    "args": {
        "deviceType": "iPhone 14",
        "runtime": "iOS 17.0"
    }
}

{
    "tool": "ios_boot_simulator",
    "args": {
        "simulatorId": "iPhone-14-simulator"
    }
}

iOS高级元素位置

{
    "tool": "ios_predicate_locate",
    "args": {
        "predicate": "type == 'XCUIElementTypeButton' AND label CONTAINS 'Login'",
        "multiple": false,
        "timeout": 10000
    }
}

{
    "tool": "ios_class_chain_locate",
    "args": {
        "classChain": "**/XCUIElementTypeTable/XCUIElementTypeCell[1]",
        "multiple": true
    }
}

Android模拟器管理

{
    "tool": "android_create_emulator",
    "args": {
        "name": "test-emulator",
        "device": "pixel_6",
        "apiLevel": "33"
    }
}

{
    "tool": "android_boot_emulator",
    "args": {
        "emulatorId": "emulator-5554",
        "options": {
            "noWindow": false,
            "gpu": "swiftshader_indirect"
        }
    }
}

Android高级元素位置

{
    "tool": "android_uiautomator_locate",
    "args": {
        "selector": "new UiSelector().className(\"android.widget.Button\").textContains(\"Submit\")",
        "multiple": false
    }
}

{
    "tool": "android_datamatcher_locate",
    "args": {
        "matcher": "{\"name\": \"submit_button\", \"class\": \"android.widget.Button\"}",
        "timeout": 15000
    }
}

跨平台智能定位

{
    "tool": "smart_locate_element",
    "args": {
        "strategy": "accessibility-id",
        "locator": "login-button",
        "multiple": false,
        "timeout": 10000
    }
}

增强手势

{
    "tool": "enhanced_swipe",
    "args": {
        "direction": "right",
        "distance": 0.8,
        "velocity": 2000,
        "naturalScrolling": true
    }
}

{
    "tool": "ios_fling",
    "args": {
        "direction": "down",
        "velocity": 3000
    }
}

后备位置策略

{
    "tool": "cross_platform_locate",
    "args": {
        "primaryStrategy": "accessibility-id",
        "primaryLocator": "login-btn",
        "fallbackStrategies": [
            {
                "strategy": "id",
                "locator": "com.example:id/login_button"
            },
            {
                "strategy": "xpath",
                "locator": "//android.widget.Button[contains(@text, 'Login')]"
            }
        ],
        "timeout": 15000
    }
}

元素验证

{
    "tool": "validate_element",
    "args": {
        "elementId": "login-button",
        "visible": true,
        "enabled": true,
        "clickable": true,
        "text": "Sign In"
    }
}

定位器策略建议

{
    "tool": "get_locator_suggestions",
    "args": {
        "platform": "android"
    }
}

工作流示例

// JavaScript (pseudo-code; adapt to your MCP client library)
await mcpClient.callTool('start_session', {
    platformName: 'Android',
    platformVersion: '12.0',
    deviceName: 'emulator-5554',
    automationName: 'UiAutomator2',
    app: '/path/to/app.apk',
});

await mcpClient.callTool('find_mobile_element', {
    by: 'accessibility-id',
    value: 'username-field',
});

await mcpClient.callTool('send_mobile_keys', {
    by: 'accessibility-id',
    value: 'username-field',
    text: 'testuser@example.com',
});

await mcpClient.callTool('tap_element', {
    by: 'accessibility-id',
    value: 'login-button',
});

await mcpClient.callTool('end_session', {});

配置

MCP客户端配置

窗户：

{
    "servers": {
        "appium": {
            "command": "node",
            "args": ["C:\\path\\to\\your\\appium-mcp-server\\wrapper.cjs"]
        }
    }
}

macOS/Linux：

{
    "servers": {
        "appium": {
            "command": "node",
            "args": ["/path/to/your/appium-mcp-server/wrapper.cjs"]
        }
    }
}

环境变量

使用以下工具控制可用工具 MCP_TOOLS:

不 MCP_TOOLS 设置（或否 env 部分）：默认情况下，所有工具都可用
MCP_TOOLS 使用特定工具：只有这些工具可用

示例--默认值（所有可用工具）：

{
    "servers": {
        "appium": {
            "command": "node",
            "args": ["/path/to/appium-mcp-server/wrapper.cjs"]
        }
    }
}

示例——仅限于特定工具：

{
    "servers": {
        "appium": {
            "command": "node",
            "args": ["/path/to/appium-mcp-server/wrapper.cjs"],
            "env": {
                "MCP_TOOLS": ["start_session", "find_mobile_element", "tap_element", "send_mobile_keys"]
            }
        }
    }
}

发展

可用脚本

npm run build -构建TypeScript项目
npm run start -启动已编译的服务器
npm run dev -使用热重新加载启动开发服务器
npm run test -运行测试套件
npm run lint -运行ESLint
npm run format -使用Prettier格式化代码
npm run typecheck -运行TypeScript类型检查

项目结构

appium-mcp-server/
├── src/
│   ├── index.ts                    # Entry point
│   ├── server/
│   │   ├── server.ts              # MCP server implementation
│   │   ├── get-allowed-tools.ts   # Tool filtering logic
│   │   └── execute-tool-method.ts # Tool execution router
│   ├── appium-client/
│   │   ├── index.ts               # Main exports
│   │   ├── appium-client.ts       # Core AppiumDriver management
│   │   ├── device-manager.ts      # Device control & info
│   │   ├── element-manager.ts     # Mobile element interactions
│   │   ├── gesture-manager.ts     # Touch gestures
│   │   ├── context-manager.ts     # App context switching
│   │   ├── app-manager.ts         # App lifecycle management
│   │   ├── ios-manager.ts         # iOS-specific operations (Phase 5)
│   │   ├── android-manager.ts     # Android-specific operations (Phase 5)
│   │   ├── simulator-manager.ts   # iOS simulator management (Phase 5)
│   │   ├── emulator-manager.ts    # Android emulator management (Phase 5)
│   │   ├── enhanced-gesture-manager.ts # Platform-aware gestures (Phase 5)
│   │   ├── locator-manager.ts     # Smart locator routing (Phase 5)
│   │   ├── platform-detector.ts   # Platform detection utilities (Phase 5)
│   │   └── types.ts               # TypeScript interfaces
│   └── tools/
│       ├── index.ts               # Tool exports
│       ├── device-management.ts   # Device control tools
│       ├── element-interaction.ts # Element interaction tools
│       ├── gesture-tools.ts       # Gesture tools
│       ├── app-management.ts      # App management tools
│       ├── mobile-analysis.ts     # Mobile-specific analysis tools
│       ├── ios-tools.ts           # iOS-specific tools (Phase 5)
│       ├── android-tools.ts       # Android-specific tools (Phase 5)
│       ├── enhanced-gesture-tools.ts # Advanced gesture tools (Phase 5)
│       └── locator-tools.ts       # Smart locator tools (Phase 5)
├── wrapper.cjs                    # CommonJS wrapper
├── package.json                   # Dependencies & scripts
├── tsconfig.json                  # TypeScript configuration
├── vitest.config.ts              # Testing configuration
└── docs/                         # Documentation

故障排除

常见问题

服务器无法启动：验证是否安装了Node.js v18+和Appium Server
连接问题：确认MCP客户端配置中的绝对路径
平台特定错误：确保安装了正确的驱动程序和开发工具
设备连接问题：验证设备/仿真器是否配置正确

平台特定设置

Android设置

安装Android SDK并设置环境变量
安装UiAutor2驱动程序： appium driver install uiautomator2
启动Android模拟器或连接物理设备
验证ADB连接： adb devices

iOS设置（仅限macOS）

安装Xcode和命令行工具
安装XCUITest驱动程序： appium driver install xcuitest
启动iOS模拟器或连接物理设备
接受开发人员证书和权限

第5阶段：平台特定故障排除

iOS模拟器问题

模拟器无法启动：确保Xcode安装正确，模拟器可用
找不到xcrun命令：安装Xcode命令行工具： xcode-select --install
谓词定位器失败：验证NSredicate语法和元素层次结构
类链不工作：检查iOS版本兼容性和元素结构

Android模拟器问题

模拟器无法启动：验证Android SDK安装和模拟器映像
ADB连接失败：检查USB调试是否已启用，设备是否已授权
UiAutomator选择器故障：验证Android API级别和选择器语法
DataMatcher不工作：检查Android版本和DataMatcher格式

跨平台问题

平台检测失败：确保在会话开始时提供正确的功能
智能定位器路由问题：检查是否安装了特定于平台的驱动程序
增强手势不起作用：验证平台兼容性和手势参数
回退策略失败：确保所有回退定位器对平台有效

贡献

请参阅 docs/ 文件夹中提供详细的贡献指南、API文档和开发设置说明。

许可证

MIT许可证

该项目遵循经过验证的Selenium MCP服务器架构，同时适应Appium移动自动化的独特要求。

使用说明

Appium MCP服务器

特性

🚀 第5阶段：平台特定增强

iOS特定功能

Android特定功能

跨平台能力

高级功能

先决条件

安装

使用pnpm

使用纱线

使用pnpm

使用纱线

使用示例

MCP客户端集成

工具调用示例

第5阶段：高级平台特定示例

iOS模拟器管理

iOS高级元素位置

Android模拟器管理

Android高级元素位置

跨平台智能定位

增强手势

后备位置策略

元素验证

定位器策略建议

工作流示例

配置

MCP客户端配置

环境变量

发展

可用脚本

项目结构

故障排除

常见问题

平台特定设置

Android设置

iOS设置（仅限macOS）

第5阶段：平台特定故障排除

iOS模拟器问题

Android模拟器问题

跨平台问题

贡献

许可证

相关 MCP

移动自动化MCP服务器

3D Slicer模型协议集成工具

博物馆艺术收藏搜索服务

Unity MCP 桥接服务

Cloudflare MCP 服务器

GCP资源管理工具