Appium MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务端，用于向 LLM 客户端提供移动端自动化相关的资源、工具（Tools）和提示模板（Prompts），并通过 JSON-RPC 协议实现请求/应答。服务器核心通过 FastMCP 搭建，注册资源与工具，提供会话管理与能力声明，支持多种传输方式（如 STDIO、HTTP 流）。

• 主要功能点

  • 资源管理：提供可渲染的资源（如页面对象、设备列表、测试代码模板等），便于 LLM 客户端展示和选择。
  • 工具注册与执行：提供大量与 Appium 移动自动化相关的工具（创建会话、删除会话、截图、定位元素、滚动、滑动、互动等），允许 LLM 调用外部功能。
  • 提示模板与文档化支持：内置文档查询、Locators 生成、测试代码生成等工具，辅助生成可执行的测试脚本。
  • 会话管理与能力声明：支持本地/远程 Appium 服务的会话创建与清理，能力配置可与外部配置合并（capabilities），并对会话生命周期进行管理。
  • 多传输协议：默认 STDIO，支持 httpStream（SSE）等传输方式，便于与不同客户端集成。
  • 安全与可扩展性：对工具执行做了日志记录和参数 redact，便于审计与调试；提供丰富的 UI 资源，方便在 MCP 客户端展示。

• 安装与运行步骤

  • 1. 确保本地环境具备 Node.js 与 npm/yarn，推荐版本与依赖在 README/Scripts 中给出。
  • 2. 安装依赖并编译运行：通过 MCP 的标准启动方式启动服务端（通常使用 npm/yarn 进行安装并执行启动命令）。
  • 3. 启动后，客户端（LLM）通过 MCP 协议与服务器通信，发送资源/工具请求，获取响应并呈现 UI（如设备选择、会话仪表盘等）。
  • 4. 服务器支持两种传输模式：stdio 与 HTTP stream（SSE）。通过启动参数选择，示例如下。

• 服务器配置（MCP 客户端使用的配置 JSON 示例） 注意：以下为 JSON 形式的描述性配置信息，具体键名与字段请按客户端实现读取并封装；该配置用于 MCP 客户端理解如何启动并连接到 MCP 服务器。

  { "appium-mcp": { "disabled": false, "timeout": 100, "type": "stdio", "command": "npx", "args": ["appium-mcp@latest"], "env": { "CAPABILITIES_CONFIG": "/path/to/your/capabilities.json" } // 说明： // - disabled: 是否禁用该 MCP 服务器条目 // - timeout: 请求超时（单位：秒或毫秒，按客户端约定） // - type: 传输类型，stdio 表示标准输入/输出，亦可配置为 httpStream 等 // - command 与 args: 启动 MCP 服务器的命令及参数 // - env: 环境变量，CAPABILITIES_CONFIG 可以指定默认能力配置文件路径 } }

• 基本使用方法

  • 1. 启动 MCP 服务器
    • 在服务器端以配置好的命令启动 MCP 服务器（如使用 npx appium-mcp@latest），服务器将暴露 MCP 接口与资源、工具等。
  • 2. 配置 MCP 客户端
    • 使用客户端（LLM 集成或专门的 MCP 客户端）通过 MCP 协议与服务器通信，基于上面的配置信息建立连接。
  • 3. 使用流程
    • 通过工具调用创建会话、获取设备、执行交互操作、生成定位信息、获取页面源、截图等。
    • 资源可用于呈现 UI（如设备选择、页面级模板、测试代码等），工具用于实际执行自动化操作。
  • 4. 传输和调试
    • 根据需要选择 stdio 或 httpStream（SSE）传输，结合日志输出进行调试和监控。
  • 5. 注意事项
    • 运行 Appium 客户端需要正确配置 CAPABILITIES_CONFIG、ANDROID_HOME、Xcode 等环境变量（由项目 README 提供的示例指南指引）。
    • 对敏感参数进行日志脱敏处理，避免在日志中暴露口令、Token 等信息。

• 其他

  • 服务器已实现丰富的工具集合覆盖平台、会话、上下文、元素操作、应用管理、导航、截图、文档查询等场景，便于将 LLM 与 Appium 自动化能力结合。