android-puppeteer-mcp

mcp-name: io.github.pedro-rivas/android-puppeteer-mcp

Android Puppeteer 是一个轻量、以视觉为先的 MCP（Model Context Protocol）服务，支持 AI Agent 通过智能 UI 元素检测和自动化交互来操控 Android 设备。它基于 uiautomator2 构建，提供全面的 Android 自动化功能，包括视觉元素检测、触控交互、文本输入和视频录制。

🎥 观看演示

功能特性

• 视觉元素检测 自动检测交互式 UI 元素，并为其添加带编号的覆盖标记，以便精准定位。

• 全面的触控交互 支持点击、长按、滑动、滚动和拖动手势，并可精准定位坐标。

• 多设备支持 可同时连接多个 Android 设备或模拟器，并针对特定设备进行操作。

• 视频录制集成 内置基于 scrcpy 的屏幕录制功能，适用于文档编写和测试工作流。

• 实时 UI 分析 实时解析 UI 层级并提取元素信息，以制定动态交互策略。

• MCP 协议集成 可与 Claude Desktop 和其他兼容 MCP 的 AI 平台无缝集成。

支持的操作系统

• Android 10+
• Windows、macOS、Linux（主机系统）

安装

先决条件

• Python 3.10+
• uiautomator2
• Android 10+（模拟器或实体设备）
• ADB（Android Debug Bridge）
• 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. 设置 Android 设备

# Enable USB debugging on your Android device
# For emulator, ensure it's running
adb devices  # Verify device connection

4. 连接到 MCP 服务

5. 找到 Claude Desktop 配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

6. 将以下 JSON 添加到 Claude Desktop 配置中：

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

   替换：

   • 将 path/to/uv 替换为 uv 可执行文件的实际路径
   • 将 path/to/android-puppeteer 替换为克隆此代码库所在位置的绝对路径

7. 重启 Claude Desktop

重启 Claude Desktop。你应能看到 "android-puppeteer" 已列为可用集成。

---

可用工具

Android Puppeteer 提供以下工具，可全面操控 Android 设备：

设备管理

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

视觉交互

• take_screenshot：截取带编号 UI 元素覆盖标记的截图
• press：点击指定坐标，可选择设置长按时长
• long_press：在指定坐标执行长按手势

导航与输入

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

录制与文档

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

使用示例

基本设备交互

# Take an annotated screenshot
screenshot = await take_screenshot()

# Tap on a specific element (element 5 from screenshot)
await press(x=500, y=300)

# Type text into an input field
await type_text("Hello, Android!")

# Swipe to scroll down
await swipe(direction="down")

多设备自动化

# List available devices
devices = await list_emulators()

# Target specific device
await take_screenshot(device_id="emulator-5554")
await press(x=200, y=400, device_id="emulator-5554")

视频录制工作流

# Start recording
await record_video(filename="test_session.mp4")

# Perform automation steps
await press(x=300, y=500)
await type_text("Automated test input")

# Stop recording
await stop_video()

项目结构

android-puppeteer/
    puppeteer.py          # Main MCP server implementation
    main.py              # Entry point
    pyproject.toml       # Project configuration
    ss/                  # Screenshots directory
    videos/              # Video recordings directory
    README.md           # This file

重要说明

• 设备权限：确保目标 Android 设备已启用 USB 调试
• 网络访问：部分功能需要网络连接以便与设备通信
• 存储：屏幕截图和视频文件保存在本地的 ss/ 和 videos/ 目录中
• 性能：响应时间取决于设备性能和网络延迟

故障排除

常见问题

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

调试模式

直接运行服务进行调试：

uv run puppeteer.py

许可证

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

贡献

欢迎贡献！欢迎提交 Pull Request。对于重大更改，请先提交 issue，讨论您希望进行的更改。

开发环境设置

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. 创建 Pull Request

相关项目

• Android MCP - 另一款 Android 自动化 MCP 服务
• uiautomator2 - 核心 Android 自动化库
• MCP Protocol - Model Context Protocol 规范

---

如果觉得有用，请为此仓库点星！