MCP Appium Server

🚀 MCP Appium Server

Model Context Protocol (MCP) Appium 服务器 — 一个 Node.js 服务器，它将移动自动化功能作为 MCP 工具提供给大语言模型（LLM）代理。

状态 - 仍在开发中

🚀 快速开始

前提条件

1. Node.js 18+

   node --version  # 版本应 >= 18.0.0
   

2. Appium 2.x

   npm install -g appium
   appium driver install uiautomator2  # 用于 Android
   appium driver install xcuitest      # 用于 iOS
   

3. Android 环境设置（用于 Android 测试）

   • 安装 Android SDK
   • 有可用的模拟器或物理设备
   • adb devices 能显示你的设备

4. iOS 环境设置（用于 iOS 测试）

   • 安装 Xcode（仅适用于 macOS）
   • 有可用的 iOS 模拟器
   • 安装 Xcode 命令行工具

安装

1. 克隆项目并安装依赖：

   cd mcp-appium-server
   npm install
   

2. 构建 TypeScript 代码：

   npm run build
   

3. 测试服务器（可选）：

   npm start
   # 服务器将启动并监听标准输入输出
   # 按 Ctrl+C 停止
   

使用方法

方式一：直接执行

node dist/index.js

服务器将：

• 开始监听标准输入输出
• 首次创建会话时自动启动 Appium
• 处理 SIGINT/SIGTERM 信号以实现优雅关闭

方式二：MCP 客户端配置

配置你的 MCP 客户端（例如 Claude Desktop、自定义 LLM 代理）以使用此服务器：

示例 MCP 配置 (~/.mcp/config.json)：

{
  "mcpServers": {
    "appium": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-appium-server/dist/index.js"],
      "env": {}
    }
  }
}

✨ 主要特性

Model Context Protocol (MCP) 是什么？

Model Context Protocol (MCP) 是一个开放协议，它规范了应用程序如何向大语言模型（LLM）提供上下文。可以将其视为一个通用适配器，允许像 GPT - 4 或 Claude 这样的 AI 代理与外部工具和服务进行交互。

关键概念

• MCP 服务器：向 LLM 代理提供功能（工具、资源、提示）的程序
• MCP 客户端：使用这些功能的 LLM 代理或应用程序
• 工具：LLM 可以调用以执行操作的函数（例如，点击按钮、输入文本）
• stdio 传输：通过标准输入输出进行通信（非常适合本地执行）

为什么在移动自动化中使用 MCP？

无需编写命令式测试脚本，你可以用自然语言描述你要测试的内容。LLM 代理会：

1. 理解你的意图
2. 调用 MCP 工具与移动应用进行交互
3. 观察结果（截图、元素状态）
4. 自主做出决策
5. 提供人类可读的报告

这不是一个测试框架 — 而是一个由 LLM 控制的移动自动化控制平面。

架构

┌─────────────────────────────────────┐
│   LLM Agent (GPT-4 / Claude)        │
│   "Tap the login button"            │
└────────────┬────────────────────────┘
             │ MCP Protocol
             │ (stdio)
             ▼
┌─────────────────────────────────────┐
│   MCP Appium Server (Node.js)       │
├─────────────────────────────────────┤
│  • Tool Registry (6 tools)          │
│  • Session Manager (stateful)       │
│  • Appium Launcher                  │
│  • Command Executor (WebdriverIO)   │
└────────────┬────────────────────────┘
             │ WebDriver Protocol
             ▼
┌─────────────────────────────────────┐
│   Appium Server (2.x)               │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│   Android Emulator / iOS Simulator  │
└─────────────────────────────────────┘

MCP 工具

此服务器提供 6 个生产就绪的 MCP 工具：

1. create_mobile_session

用途：为 Android 或 iOS 创建一个 Appium 会话

输入：

{
  "platform": "android | ios",
  "capabilities": {
    "deviceName": "Pixel_5_API_31",
    "app": "/path/to/app.apk",
    "automationName": "UiAutomator2"
  }
}

输出：

{
  "success": true,
  "sessionId": "abc123...",
  "platform": "android"
}

2. tap_element

用途：点击 UI 元素

输入：

{
  "sessionId": "abc123...",
  "strategy": "id | xpath | accessibilityId",
  "selector": "com.example:id/login_button"
}

3. type_text

用途：在元素中输入文本

输入：

{
  "sessionId": "abc123...",
  "strategy": "accessibilityId",
  "selector": "username_field",
  "text": "testuser@example.com"
}

4. navigate_back

用途：按下返回按钮（Android）或返回上一页（iOS）

输入：

{
  "sessionId": "abc123..."
}

5. take_screenshot

用途：捕获当前屏幕状态

输入：

{
  "sessionId": "abc123..."
}

输出：

{
  "success": true,
  "imageBase64": "iVBORw0KGgoAAAANSUhEU...",
  "format": "png"
}

6. close_mobile_session

用途：关闭会话并清理资源

输入：

{
  "sessionId": "abc123..."
}

示例 LLM 对话

用户：“为计算器应用启动一个 Android 会话，然后点击数字 5 按钮”

LLM 代理（内部推理）：

1. 使用 Android 功能调用 create_mobile_session
2. 接收会话 ID
3. 使用“5”按钮的选择器调用 tap_element
4. 向用户返回成功信息

结果：计算器应用打开并自动点击“5”。

📚 详细文档

项目结构

mcp-appium-server/
├── src/
│   ├── index.ts                  # 入口点，信号处理
│   ├── mcp/
│   │   ├── server.ts             # MCP 服务器设置和工具注册
│   │   └── tools.ts              # 工具实现
│   ├── appium/
│   │   ├── appiumLauncher.ts     # 启动/停止 Appium 进程
│   │   ├── sessionManager.ts     # 会话生命周期和状态管理
│   │   └── commandExecutor.ts    # WebDriver 命令映射
│   └── types/
│       └── toolSchemas.ts        # 工具的 JSON 模式
├── package.json
├── tsconfig.json
└── README.md

设计原则

1. 符合 MCP 标准

• 遵循 MCP 规范进行工具注册
• 使用 stdio 传输
• 带有错误代码的结构化错误处理

2. 无状态工具，有状态会话

• 每个工具调用都是幂等的
• 会话状态在内存中管理
• 显式传递会话 ID

3. 对自主代理安全

• 不暴露破坏性命令
• 优雅的错误处理
• 每次调用时进行会话验证

4. 生产级质量

• 全面的日志记录（Winston）
• TypeScript 严格模式
• 带有清理功能的优雅关闭

错误处理

所有错误都以符合 MCP 的结构化错误形式返回：

{
  "error": {
    "code": "InternalError",
    "message": "Session not found: xyz123. Create a session first using create_mobile_session."
  }
}

常见错误：

• Session not found：先调用 create_mobile_session
• Element not found：检查你的选择器策略/值
• Appium startup timeout：确保 Appium 已安装并在系统路径中

已知限制

1. 仅支持本地执行：目前不支持云设备农场
2. 仅支持 stdio 传输：目前不支持 WebSocket/HTTP
3. 基本元素交互：目前不支持手势（滑动、捏合）
4. 无辅助功能树导出：未来版本将支持
5. 无视觉集成：截图分析需要外部 LLM 视觉功能

未来扩展

• 🔄 手势支持（滑动、滚动、捏合）
• 🌳 辅助功能树导出，以便更好地发现元素
• 📸 视觉 API 集成，用于截图分析
• 🌐 WebSocket 传输，用于远程执行
• ☁️ 云设备农场支持（BrowserStack、Sauce Labs）
• 🔍 增强元素发现，使用 AI 驱动的选择器

故障排除

"Appium startup timeout"

解决方案：确保 Appium 已全局安装：

npm install -g appium
appium --version

"Session creation failed"

解决方案：检查设备可用性：

# Android
adb devices

# iOS
xcrun simctl list devices

"Element not found"

解决方案：先截取屏幕截图以验证元素的可见性：

{
  "tool": "take_screenshot",
  "input": { "sessionId": "..." }
}

贡献

这是一个用于 LLM 控制的移动自动化的生产级 MCP 服务器。欢迎贡献代码！

设计指南：

• 保持工具简单且可组合
• 绝不暴露原始的 WebDriver API
• 保持向后兼容性
• 使用真实的 LLM 代理进行测试

📄 许可证

ISC

致谢

使用以下工具构建：

• @modelcontextprotocol/sdk - MCP 协议实现
• Appium - 移动自动化框架
• WebdriverIO - WebDriver 客户端
• Winston - 日志记录

有疑问？ 查看 Model Context Protocol 文档 或提交一个 issue。