Android Puppeteer MCP

🚀 Android Puppeteer

Android Puppeteer は、軽量で視覚重視のMCP（Model Context Protocol）サーバーです。これにより、AIエージェントは、インテリジェントな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デバイスをセットアップする

# AndroidデバイスでUSBデバッグを有効にする
# エミュレーターの場合は、起動していることを確認する
adb devices  # デバイスの接続を確認する

4. MCPサーバーに接続する

5. Claude Desktopの設定ファイルを見つける：

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

6. 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 をこのリポジトリをクローンした絶対パスに置き換える

7. Claude Desktopを再起動する

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/
    puppeteer.py          # 主要なMCPサーバーの実装
    main.py              # エントリーポイント
    pyproject.toml       # プロジェクトの設定
    ss/                  # スクリーンショットのディレクトリ
    videos/              # ビデオ録画のディレクトリ
    README.md           # このファイル

重要な注意事項

• デバイスの権限：対象のAndroidデバイスでUSBデバッグが有効になっていることを確認してください。
• ネットワークアクセス：一部の機能では、デバイス通信のためにネットワーク接続が必要です。
• ストレージ：スクリーンショットとビデオファイルは、ss/ と videos/ ディレクトリにローカルに保存されます。
• パフォーマンス：応答時間は、デバイスのパフォーマンスとネットワークの遅延に依存します。

トラブルシューティング

一般的な問題

1. デバイスが見つからない：adb devices でADB接続を確認してください。
2. 権限が拒否された：USBデバッグとデバイスの認証を確認してください。
3. スクリーンショットが失敗した：デバイスの画面がロック解除され、アクセス可能であることを確認してください。
4. ビデオ録画の問題：scrcpyのインストールとデバイスの互換性を確認してください。

デバッグモード

デバッグのためにサーバーを直接実行するには：

uv run puppeteer.py

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細は LICENSE を参照してください。

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。大きな変更の場合は、まず変更したい内容を議論するためのイシューを開いてください。

開発環境のセットアップ

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 - モデルコンテキストプロトコルの仕様

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