金大哥 - android-puppeteer-mcp MCP 详情

article

README

🚀 Android Puppeteer

Android Puppeteer 是一款轻量级、以视觉为优先的 MCP（模型上下文协议）服务器，它通过智能的 UI 元素检测和自动交互功能，让 AI 代理能够与安卓设备进行交互。该项目基于 uiautomator2 构建，具备全面的安卓自动化能力，涵盖视觉元素检测、触摸交互、文本输入和视频录制等功能。

🎥 观看演示视频

🚀 快速开始

前提条件

Python 3.10 及以上版本
uiautomator2
安卓 10 及以上版本（模拟器或真机均可）
ADB（安卓调试桥）
scrcpy（用于视频录制功能）

操作步骤

克隆仓库

git clone https://github.com/pedro-rivas/android-puppeteer-mcp.git
cd android-puppeteer

安装依赖

uv python install 3.10
uv sync

配置安卓设备

# 在安卓设备上启用 USB 调试功能
# 若使用模拟器，请确保其已启动
adb devices  # 验证设备连接情况

连接到 MCP 服务器
- 找到你的 Claude Desktop 配置文件：
  - Windows 系统：%APPDATA%\Claude\claude_desktop_config.json
  - macOS 系统：~/Library/Application Support/Claude/claude_desktop_config.json
- 在 Claude Desktop 配置文件中添加以下 JSON 内容：

{
    "mcpServers": {
        "android-puppeteer": {
            "command": "path/to/uv",
            "args": [
                "--directory",
                "path/to/android-puppeteer",
                "run",
                "puppeteer.py"
            ]
        }
    }
}

请将 `path/to/uv` 替换为你的 uv 可执行文件的实际路径，将 `path/to/android-puppeteer` 替换为你克隆此仓库的绝对路径。
- **重启 Claude Desktop**：重启后，你应该能在可用集成列表中看到 “android-puppeteer”。

✨ 主要特性

视觉元素检测：自动检测并使用编号覆盖层标注交互式 UI 元素，实现精确目标定位。
全面的触摸交互：支持点击、长按、滑动、滚动和拖动等手势，可基于坐标进行精确操作。
多设备支持：可同时连接多个安卓设备或模拟器，并针对特定设备进行操作。
视频录制集成：内置使用 scrcpy 的屏幕录制功能，适用于文档记录和测试工作流程。
实时 UI 分析：实时解析 UI 层级结构并提取元素信息，以实现动态交互策略。
MCP 协议集成：可与 Claude Desktop 及其他支持 MCP 的 AI 平台无缝集成。

支持的操作系统

安卓 10 及以上版本
Windows、macOS、Linux（主机系统）

📦 安装指南

前置要求

Python 3.10+
uiautomator2
Android 10+（模拟器或真机）
ADB（Android 调试桥）
scrcpy（用于视频录制功能）

开始安装

克隆仓库

git clone https://github.com/pedro-rivas/android-puppeteer-mcp.git
cd android-puppeteer

安装依赖

uv python install 3.10
uv sync

配置安卓设备

# 在安卓设备上启用 USB 调试
# 若使用模拟器，需确保其正在运行
adb devices  # 验证设备连接情况

连接到 MCP 服务器
1. 找到你的 Claude Desktop 配置文件：
  - Windows：%APPDATA%\Claude\claude_desktop_config.json
  - macOS：~/Library/Application Support/Claude/claude_desktop_config.json
2. 在 Claude Desktop 配置文件中添加以下 JSON 内容：

{
    "mcpServers": {
        "android-puppeteer": {
            "command": "path/to/uv",
            "args": [
                "--directory",
                "path/to/android-puppeteer",
                "run",
                "puppeteer.py"
            ]
        }
    }
}

请将 `path/to/uv` 替换为你的 uv 可执行文件的实际路径，将 `path/to/android-puppeteer` 替换为你克隆此仓库的绝对路径。
3. **重启 Claude Desktop**：重启后，你应该能在可用集成列表中看到 “android-puppeteer”。

💻 使用示例

基础用法

# 拍摄带标注的屏幕截图
screenshot = await take_screenshot()

# 点击特定元素（截图中的元素 5）
await press(x=500, y=300)

# 在输入框中输入文本
await type_text("Hello, Android!")

# 向下滑动屏幕
await swipe(direction="down")

高级用法

多设备自动化

# 列出可用设备
devices = await list_emulators()

# 针对特定设备操作
await take_screenshot(device_id="emulator-5554")
await press(x=200, y=400, device_id="emulator-5554")

视频录制工作流程

# 开始录制
await record_video(filename="test_session.mp4")

# 执行自动化操作
await press(x=300, y=500)
await type_text("Automated test input")

# 停止录制
await stop_video()

📚 详细文档

可用工具

Android Puppeteer 提供了以下用于与安卓设备进行全面交互的工具：

设备管理

list_emulators：列出所有可用的安卓模拟器和设备，并显示其状态和屏幕尺寸。
get_device_dimensions：获取特定安卓设备的屏幕尺寸。
get_ui_elements_info：获取屏幕上所有交互式 UI 元素的详细信息。

视觉交互

take_screenshot：拍摄带编号 UI 元素覆盖层的标注截图。
press：在指定坐标处点击，可选择设置长按时间。
long_press：在指定坐标处执行长按手势。

导航与输入

press_back：按下硬件返回按钮。
swipe：执行定向或自定义坐标的滑动操作。
type_text：在聚焦的输入框中输入文本，可选择清除原有文本。
scroll_element：向任意方向滚动特定的 UI 元素。

录制与文档记录

record_video：以可自定义的质量设置开始屏幕录制。
stop_video：停止正在进行的屏幕录制并保存到本地存储。

项目结构

android-puppeteer/
    puppeteer.py          # 主 MCP 服务器实现文件
    main.py              # 入口文件
    pyproject.toml       # 项目配置文件
    ss/                  # 截图目录
    videos/              # 视频录制目录
    README.md           # 本文件

重要提示

⚠️ 重要提示

设备权限：确保目标安卓设备已启用 USB 调试功能。

网络访问：部分功能需要网络连接以进行设备通信。

存储：截图和视频文件将保存在本地的 ss/ 和 videos/ 目录中。

性能：响应时间取决于设备性能和网络延迟。

故障排除

常见问题

设备未找到：使用 adb devices 验证 ADB 连接。
权限被拒绝：检查 USB 调试和设备授权情况。
截图失败：确保设备屏幕已解锁且可访问。
视频录制问题：验证 scrcpy 安装情况和设备兼容性。

调试模式

直接运行服务器进行调试：

uv run puppeteer.py

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献代码

欢迎贡献代码！请随时提交拉取请求。对于重大更改，请先创建一个问题，讨论你想要进行的更改。

开发环境设置

Fork 此仓库。
创建一个特性分支（git checkout -b feature/amazing-feature）。
进行更改。
运行测试并确保代码质量。
提交更改（git commit -m 'Add amazing feature'）。
将更改推送到分支（git push origin feature/amazing-feature）。
打开一个拉取请求。

android-puppeteer-mcp