Android Puppeteer MCP

🚀 Android Puppeteer

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

🎥 观看演示视频

🚀 快速开始

前提条件

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

操作步骤

1. 克隆仓库

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

2. 安装依赖

uv python install 3.10
uv sync

3. 配置安卓设备

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

4. 连接到 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（用于视频录制功能）

开始安装

1. 克隆仓库

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

2. 安装依赖

uv python install 3.10
uv sync

3. 配置安卓设备

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

4. 连接到 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/ 目录中。
• 性能：响应时间取决于设备性能和网络延迟。

故障排除

常见问题

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

调试模式

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

uv run puppeteer.py

📄 许可证

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

贡献代码

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

开发环境设置

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

相关项目

• Android MCP - 另一个安卓自动化 MCP 服务器。
• uiautomator2 - 核心安卓自动化库。
• MCP 协议 - 模型上下文协议规范。

如果觉得这个仓库有用，请给它点个星！