shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-appium-server

这是一个基于Model Context Protocol（MCP）的Node.js服务器，它将Appium移动自动化能力封装成MCP工具，使LLM智能体能够通过自然语言指令控制Android或iOS应用，实现自动化测试与交互。

article

README

🚀 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

致谢

使用以下工具构建：

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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端