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 協議 - 模型上下文協議規範。

如果覺得這個倉庫有用，請給它點個星！