Name: Android自动化服务
Author: pedro-rivas

使用说明

MCP名称：io.github.pedro-rivas/android-puppeteer-mcp

Android Puppeteer

Android Puppeteer（安卓版Puppeteer） 这是一个轻量级、以视觉优先的MCP（模型上下文协议）服务器，它使AI代理能够通过智能UI元素检测和自动化交互与Android设备进行互动。该服务器基于uiautomator2构建，提供了全面的Android自动化功能，包括视觉元素检测、触摸交互、文本输入和视频录制。

🎥（电影胶片或摄像机的符号，无直接对应中文翻译，可理解为“电影”或“摄像机”的意象） 观看演示实际运行情况

特点/功能

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

支持的操作系统

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

安装

先决条件

Python 3.10+（或译为：Python 3.10及以上版本）
uiautomator2（注：这是一个自动化测试框架的名称，直接翻译为中文仍为“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

设置Android设备

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

连接到MCP服务器
找到您的Claude桌面配置文件：
- Windows： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

将以下 JSON 添加到您的 Claude 桌面配置中：

{
  "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桌面版

重启您的Claude桌面应用。您应该会看到“android-puppeteer”列在可用集成中。

可用工具

Android Puppeteer 提供了以下工具，以实现全面的 Android 设备交互：

设备管理

**list_emulators**列出所有可用的Android模拟器和设备，包括它们的状态和尺寸
**get_device_dimensions**获取特定Android设备的屏幕尺寸
**get_ui_elements_info**获取屏幕上所有交互式用户界面元素的详细信息

视觉交互

**take_screenshot**捕获带有编号UI元素覆盖层的注释截图
**press**点击特定坐标，可选择长按持续时间
**long_press**在特定坐标上执行长按手势

导航与输入

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

记录与文档编制

**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/ 目录（或文件夹）
演出响应时间取决于设备性能和网络延迟

故障排除

常见问题

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

调试模式

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

uv run puppeteer.py

许可证

这个项目遵循MIT许可证授权。请参阅许可证详情如下。

贡献

欢迎贡献！请随时提交拉取请求。对于重大更改，请先打开一个议题进行讨论，说明您想要更改的内容。

开发环境设置

克隆（或“分叉”）该仓库
创建一个特性分支（git checkout -b feature/amazing-feature）
进行你的更改
运行测试并确保代码质量
提交您的更改（git commit -m 'Add amazing feature')
推送至分支（git push origin feature/amazing-feature）
提交一个拉取请求