android-puppeteer-mcp

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

Android Puppeteer は、インテリジェントな UI 要素検出と自動操作を通じて、AI エージェントが Android デバイスを操作できるようにする、軽量でビジュアルを重視した MCP（Model Context Protocol）サーバーです。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 の下でライセンスされています。詳細は LICENSE を参照してください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。大きな変更を加える場合は、まず issue を開いて、変更したい内容についてご相談ください。

開発環境のセットアップ

1. リポジトリをフォークします
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 - Android 自動化向けの代替 MCP サーバー
• uiautomator2 - Android 自動化のコアライブラリ
• MCP Protocol - Model Context Protocol の仕様

---

役に立った場合は、このリポジトリにスターを付けてください！