Agent Droid Bridge

Agent Droid Bridge

Agent Droid Bridge は、ADB 経由で AI エージェントを Android デバイスやエミュレーターに接続する MCP サーバーです。モバイル自動化、アプリのテスト、動的解析、リバースエンジニアリング向けに構築されており、ADB の全機能を構造化されたツールとして公開し、MCP 対応の AI クライアントから直接呼び出せます。ADB でできることは、すべてエージェントで実行できます。

---

目的に特化したツールは、構造化された最小限の応答を返します。生の XML ダンプも、コンテキストの無駄遣いもありません。エージェントは長時間のセッションでも高速に動作します。

デモ

上のデモでは、接続されたエージェントにできることを示すため、いくつかの簡単なタスクを実行しています。これは機能のほんの一部にすぎません。

• Paint アプリをインストールして開き、壁と屋根のピクセル座標を計算して家を描きます
• デバイスのブラウザーを開いて「MCP Wikipedia」を検索し、検索結果ページに移動してスクリーンショットを撮ります
• Calculator を開いて 1337 × 42 を計算し、結果をホストマシンに取り出します
• Contacts を開いて名前と電話番号を登録し、保存されたことを確認します
• Calendar を開き、指定した日付に予定を登録します
• Settings を開いてダークモードを切り替えます
• デバイスから Calculator の APK をホストマシンに取り出します
• Notepad をインストールし、完了したすべてのタスクを一文で要約して書き込み、最後にスクリーンショットを撮ります

機能

ツール

• 画面キャプチャ、UI の検査、テキストの読み取り、要素の抽出、タッチおよびスワイプ入力、テキスト入力、キーコードイベント、アプリの起動、ADB コマンド、デバイスの検査に対応する、組み込みツール 14 種
• app_manager パックに、パッケージ管理、アプリのライフサイクル管理、APK の抽出、権限、インテントの注入に対応するツール 9 種が追加されます。ADB_EXTRA_TOOL_PACKS=app_manager で読み込めます
• 利用可能なツールは、サーバーの起動時の指示に反映されます。エージェントは接続時に正確なカタログを受け取ります

デバイスの処理

• 接続されているデバイスが 1 台の場合は自動検出し、複数台ある場合は選択を求めます
• stdio 経由で動作し、MCP 対応のあらゆる AI クライアントと互換性があります
• 生の XML ダンプではなく構造化された応答を返すため、長時間の自動化処理でもエージェントのコンテキストを簡潔に保てます

セキュリティ

• 2 つの実行モードがあります。unrestricted（フル ADB アクセス。任意で拒否リストを設定可能）と、restricted（許可リストのみ。明示的に許可されていない操作をすべてブロック）
• ADB_ALLOW_SHELL=false を設定すると、モードに関係なく、すべてのシェルコマンドが無効になります
• ADB_DENIED_TOOLS を使って、エージェントから特定のツールを非表示にできます
• すべてのコマンドは shlex で解析されるため、シェルインジェクションは発生しません

可観測性

• オプションのセッションレコーダーを使うと、すべてのツール呼び出し、ADB コマンド、セキュリティイベントが構造化された JSONL ファイルに記録されます。MCP_LOG_ENABLED=true と MCP_LOG_DIR を設定して有効にします

ユースケース

モバイル QA とテストの自動化 アプリを変更したりテストコードを書いたりせずに、実機やエミュレーター上の UI フローを自動化できます。自然言語のプロンプトだけで、タップ、スワイプ、入力、画面コンテンツの読み取り、スクリーンショットの撮影を実行できます。

アプリのセキュリティ調査 APK の抽出、宣言された権限の検査、任意のインテントの送信、画面上での実行時の動作の観察が可能です。計測もジェイルブレイクも必要ありません。

動的解析 制御された状態でアプリを起動し、UI 操作を実行して各ステップの画面状態をキャプチャし、成果物を取得できます。すべて AI エージェントを通じてスクリプト化できます。

開発とデバッグ 開発環境を離れることなく、ビルドのインストール、UI 状態の確認、アプリ情報のチェック、ADB コマンドの実行が可能です。

インストール

uvx agent-droid-bridge

リポジトリのクローンや仮想環境の作成は不要です。Python 3.11+ と、ホストへの ADB のインストールが必要です。

uvx は uv に含まれています。インストールされていない場合：curl -LsSf https://astral.sh/uv/install.sh | sh

ソースからインストールする場合は、docs/setup.md — オプション B を参照してください。

インストールを確認するには：uvx agent-droid-bridge --help

クイックスタート

1. ADB をインストールします。プラットフォーム別の手順については、docs/setup.md を参照してください
2. Android デバイスを接続するか、エミュレーターを起動します
3. MCP クライアントの設定にサーバーを追加します：

{
  "mcpServers": {
    "agent-droid-bridge": {
      "command": "uvx",
      "args": ["agent-droid-bridge"],
      "env": {
        "ADB_EXECUTION_MODE": "unrestricted",
        "ADB_ALLOW_SHELL": "true",
        "ADB_PATH": "adb",
        "ADB_EXTRA_TOOL_PACKS": "",
        "MCP_LOG_ENABLED": "false",
        "MCP_LOG_DIR": "~/logs/agent-droid-bridge"
      }
    }
  }
}

セッションログを有効にするには、MCP_LOG_ENABLED に "true" を設定し、MCP_LOG_DIR をマシン上の書き込み可能なパスに変更します。

変数	デフォルト	説明
ADB_EXECUTION_MODE	unrestricted	セキュリティモードです。unrestricted はすべてのシェルコマンドを許可します（任意で拒否リストを設定可能）。restricted は ADB_SHELL_ALLOWLIST に含まれるコマンドのみを許可します。
ADB_ALLOW_SHELL	true	false に設定すると、実行モードに関係なく、すべての adb shell コマンドをブロックします。
ADB_PATH	adb	ADB バイナリへのパスです。システムの PATH に adb がない場合は、フルパスに置き換えてください（例：Windows の場合は C:\platform-tools\adb.exe）。
ADB_EXTRA_TOOL_PACKS	(空)	読み込む追加ツールパックをカンマ区切りで指定します。app_manager を設定すると、アプリ管理ツールが 9 種追加で有効になります。
MCP_LOG_ENABLED	false	true に設定すると、セッションログが有効になります。MCP_LOG_DIR が必要です。
MCP_LOG_DIR	(なし)	セッションログの書き込み先ディレクトリです。MCP_LOG_ENABLED が true の場合は必須です。

4. エージェントに agent-droid-bridge MCP ツールを使うようプロンプトで指示します

セットアップガイドと環境変数の一覧については、docs/setup.md を参照してください。

ツール

ツール	機能
get_ui_hierarchy	現在の画面を XML UI 階層として返します
take_screenshot	画面を base64 エンコードされた PNG としてキャプチャします
tap_screen	ピクセル座標を指定してタップジェスチャーを送信します
swipe_screen	指定した時間をかけて、2 点間のスワイプジェスチャーを送信します
type_text	フォーカスされている入力フィールドにテキストを入力します
press_key	Android のキーコードイベント（Back、Home、Enter など）を送信します
launch_app	package/activity コンポーネント名を指定してアプリを起動します
execute_adb_command	任意の ADB または ADB shell コマンドを実行します
list_devices	ADB から現在認識できるすべての Android デバイスのシリアル番号、状態、モデルを一覧表示します
snapshot_ui	軽量な UI スナップショットを取得し、detect_ui_change で使用するトークンを返します
detect_ui_change	アクション後の UI の変更をポーリングします。ベースラインとしてスナップショットトークンを受け取り、要求された場合にのみ階層を返します
get_screen_elements	UI 階層を解析し、座標やインタラクションプロパティを含む構造化された要素を返します。tappable、interactive、input、all の各モードをサポートします
get_screen_text	画面に表示されているすべてのテキストを、上から下の順にプレーンテキストで返します
check_device_capabilities	デバイスの識別情報、セキュリティ状態、ハードウェア仕様を含む構造化情報を 1 回の呼び出しで返します。identity、security、hardware、all の各モードをサポートします

追加のツールパック

オプションのパックでコアツールセットを拡張できます。MCP クライアントの設定で ADB_EXTRA_TOOL_PACKS を設定して有効にします。docs/extra-tool-packs.md を参照してください。

app_manager

パッケージ管理、アプリのライフサイクル制御、APK の抽出、権限管理、インテントの注入を行います。

ツール	機能
list_packages	インストール済みパッケージを、任意のフィルタリング、検索、詳細レベルで一覧表示します
get_app_info	インストール済みのアプリ 1 つの静的メタデータ全体を返します
install_app	ホスト上のパスからデバイスに APK をインストールします
uninstall_app	パッケージ名を指定してインストール済みアプリを削除します
pull_apk	インストール済みの APK をデバイスからホストに抽出します
manage_permission	アプリの実行時権限を付与、取り消し、確認、一覧表示します
launch_app_extra	パッケージ名でアプリを起動し、ランチャーアクティビティを自動的に解決します
manage_app	アプリの実行時状態を制御します — 停止、データの消去、キャッシュの消去、有効化、無効化
inject_intent	am start、am broadcast、または am startservice を介してコンポーネントにインテントを送信します

パラメーターの完全なリファレンス：docs/tools.md

設定

サーバーはすべて MCP クライアントの env ブロックで設定できます。編集するファイルはありません。上記のクイックスタートにある env ブロックで、最も一般的な設定を行えます。セキュリティフィルタリング、ツールの表示設定、タイムアウトを含む完全なリファレンスは、docs/configuration.md を参照してください。

代わりに YAML 設定ファイルを使用するには、ADB_CONFIG_SOURCE=yaml を設定します。詳細は docs/configuration.md を参照してください。

セッションの記録は別途設定します。MCP_LOG_ENABLED=true と MCP_LOG_DIR を設定して有効にします。完全なリファレンス：docs/logging.md。

ドキュメント

ファイル	説明
docs/setup.md	前提条件、インストール、MCP クライアントの設定
docs/tools.md	すべてのツールのパラメーターに関する完全なリファレンス
docs/configuration.md	環境変数と adb_config.yaml のリファレンス
docs/logging.md	セッションレコーダー — ログファイル、レベル、保持期間、有効化
docs/extra-tool-packs.md	追加のツールパック — パックの有効化、パックの仕様、独自のパックの作成
docs/troubleshooting.md	よくあるセットアップの問題と ADB の問題
docs/workflows.md	一般的な複数ツールのワークフローと例
CHANGELOG.md	リリース履歴とバージョンの変更

貢献

貢献を歓迎します。セットアップ、コード規約、プルリクエストの提出に関するガイドラインは、CONTRIBUTING.md を参照してください。

セキュリティの脆弱性を報告する場合は、SECURITY.md の手順に従ってください — 公開の issue は作成しないでください。