Android Phone MCP Server

使用说明（简要且易操作）

• 项目简介
  • 该仓库实现了一个 MCP 服务器端，面向 MCP 客户端提供设备控制、截图/UI 观察、应用管理、文本输入等工具，以及一个集成的自治智能体，用于在 Android 真机上执行给定目标的任务。服务器通过 JSON-RPC 的方式与客户端通信，便于 LLM 客户端以统一的协议调用能力。
• 主要功能点
  • 设备控制与状态观察：点击、滑动、输入文本、解锁、获取截图和 UI 层级树。
  • UI 观察与简化：获取完整 UI 层级树或简化后的紧凑树，便于后续推理/操作。
  • 应用管理：启动、停止、列出已安装的第三方应用。
  • 高级交互：长按、热键、坐标点击、拖拽、等待、截图等多种操作。
  • AI Agent 集成：通过 Volcengine GUI Agent 实现对屏幕的理解与行动建议，并可执行自动化任务（如 run_autonomous_task）。
  • 辅助工具：启动/停止 scrcpy 投屏等辅助操作。
• 安装步骤
  • 安装依赖
    • 使用方式请参考 README 提供的安装步骤（包括 Python 依赖和系统工具如 adb、scrcpy 的安装）。
  • 运行 MCP 服务器
    • 通过仓库提供的入口启动服务（示例：在项目根目录执行以下任意一种方式之一）
      • 使用 CLI 启动：python -m android_phone.main server
      • 使用 uvx 快速运行：uvx fastmcp run src/android_phone/server.py
  • 连接真机
    • 按照 README 的步骤通过 USB/ADB 连接 Android 设备，确保设备可被 adb 识别并由 MCP 服务调用。
• 服务器配置
  • MCP 客户端使用服务器需要一个配置（JSON），描述服务器名称、启动命令和参数等。以下为符合仓库情况的示例配置（请直接使用 JSON 形式提交给客户端，不需要在代码中嵌入）： { "server_name": "android-phone-mcp", "command": "python -m android_phone.main", "args": ["server"], "description": "Android Phone MCP 服务器，提供设备控制、UI 观察与 autonomous task 能力", "transport": "http" } 说明：
  • server_name：服务器标识名称，需与实际运行环境一致，便于管理和日志区分。
  • command：启动服务器的命令，这里指向 Python 模块入口 android_phone.main。
  • args：启动参数，在运行服务器子命令时传入 server。
  • transport（可选）：若客户端支持多种传输，注明使用的传输协议类型（如 http、ws、stdio 等，此处以 http 为常见场景）。
• 基本使用方法
  • 启动后，客户端通过 MCP 协议向服务器提交请求，获取设备信息、执行 UI 操作、进行 autonomous task 等。
  • 使用时可先调用 get_screen_state 获取屏幕快照和 UI 树（可选输出 XML）、随后依任务需求执行相应操作（tap、swipe、type、long_press 等），并可触发 run_autonomous_task 进行自动化任务执行。