brickproof-adb

brickproof-adb

AI アシスタントに、あなた自身の Android デバイス（まずは TV ボックス、さらにスマートフォンやタブレットも）を ADB 経由で管理させても、デバイスを使えなくすることはありません。

brickproof-adb は MCP サーバーです。Claude（または任意の MCP クライアント）に、デバイスの画面、入力、パッケージマネージャーへのアクセスを提供し、不注意な呼び出しによる問題を防ぐ安全策も備えています。パッケージの変更はすべて、まずドライランで確認します。デバイスに不可欠なパッケージはデバイスから読み取って変更を拒否し、現在ネットワーク上で何らかのサービスを提供しているパッケージには触れません。適用した変更はすべてスナップショットに記録され、1 回の呼び出しでロールバックできます。

Windows、macOS、Linux、Docker、および Home Assistant アプリとして動作し、デバイスは USB またはネットワーク経由で接続できます。

使用例

テレビを見つける。

あなた： テレビを探して。

Claude は adb_devices discover=true を呼び出します。まだ何も接続されていないため、デバッグを通知するデバイスと、ホームネットワーク上でポート 5555 が開いているデバイスを検索します。

Found:
  192.0.2.50:5555 (port 5555 open, network debugging) - adb_connect host=192.0.2.50:5555; if this computer is new to the device, it asks on its screen to allow debugging

Claude： 192.0.2.50 にデバイスが 1 台見つかりました。接続しますか？テレビに、デバッグを許可するかどうかが表示されます。

あなた： はい。

Claude は adb_connect host=192.0.2.50:5555 を呼び出します。テレビの画面でデバッグを許可するプロンプトを確認し、「常に許可」にチェックを入れます。アドレスは記憶され、サーバーの起動時に毎回再接続されます。

ダウンロードしたばかりのものをインストールする。

あなた： ダウンロードしたアプリをテレビにインストールして。

Claude はパスを指定せずに adb_install を呼び出し、Downloads フォルダー内の最新のインストール可能なファイルを取得します。続いて最初のファイルを指定して adb_install を呼び出し、どのデバイスに何がインストールされるかを報告します。あなたが許可すると、同じ呼び出しを dry_run=false で実行してインストールします。

TV ボックスを整理する。

あなた： ボックスの動作が遅い。プリインストールされた不要なものを無効にして。ただし、必要なものは残して。

Claude は adb_app action=list filter=system を呼び出し、5 つのパッケージを選んで adb_app action=disable を呼び出します。これはデフォルトでドライランです。計画には各パッケージのロールバック方法が示されますが、ボックスのランチャーとして使われているため、パッケージの 1 つは拒否されます。

REFUSED: the list contains protected packages - com.example.launcher.
  com.example.launcher — launcher, roles (HOME)
The full set with every source: adb_app action=protected
Nothing was applied. Remove them from the list by hand; the tool has no override.

Claude はそのパッケージを除外し、残り 4 つの計画を実行した後、dry_run=false で再度実行します。一括処理の後にアカウント数とランチャーが確認され、4 つのパッケージがスナップショットに記録されます。

あなた： 音声リモコンが動かなくなった。

Claude は adb_app action=restore を呼び出し、計画を確認してから dry_run=false で再度実行します。1 回の呼び出しですべてのパッケージが再び有効になります。

画面を見てタップする。

あなた： スマートフォンでネットワーク設定を開いて。

Claude は adb_screenshot を呼び出して画像とその下の行を取得します。

screen 1080x2340 -> image 473x1024 · scale 2.283/2.285 · pass coords="screenshot" to adb_tap/adb_swipe

そして、画像上で確認した「ネットワークとインターネット」の行を、画像内の座標を使って adb_tap coords="screenshot" でタップします。タッチスクリーンのない TV ボックスでは、adb_find_and_tap text="Network" を使い、リモコンのキーでフォーカスを移動します。

AI を使う場所にインストール

詳細、その他のセットアップ方法と確認方法については、docs/installation.mdをご覧ください。MCP に対応していない AI アプリでは、このサーバーを使用できません。

• Home Assistant — ha-adb-mcpアプリをインストールします。Home Assistant の外部アドレスを使えば、ブラウザチャットからアクセスできます。

• Claude Desktop（Windows、macOS）— 最新リリースから.mcpbファイルをダウンロードして Claude Desktop のウィンドウにドラッグするか、「Settings → Extensions → Advanced settings → Install Extension…」から選択します（アーカイバーが代わりにファイルを開かない限り、ダブルクリックでもインストールできます）。Claude Desktop に短いフォームが表示され、インストールされます。Node.js は不要です。代わりに JSON 設定を使う場合は、docs/installation.mdをご覧ください。

• Claude Code:

  claude mcp add brickproof-adb -- npx -y brickproof-adb
  

• コンピューター上のその他の MCP クライアント — サーバーコマンドはnpx -y brickproof-adbです。

• Home Assistant を使わずにブラウザでチャットする場合 — 常時稼働する自宅のコンピューターでbrickproof-adb serveを実行し、公開 HTTPS アドレスを用意する必要があります：docs/installation.md。

• Docker — ghcr.io/st412m/brickproof-adb：docs/installation.md。

初回起動

1. デバイスでデバッグを有効にします。 Android TV、Google TV、Fire TV、スマートフォンでは、設定の「デバイス情報」画面でビルド番号を7回タップすると表示される「開発者向けオプション」にあります。そこから、ケーブル接続には USB デバッグを、多くの TV ボックスではネットワークデバッグまたは ADB デバッグを、Android 11 以降のスマートフォンではワイヤレスデバッグを有効にします。
2. アシスタントに「テレビを探して」と伝えます（または「スマートフォンを探して」と伝えます）。ネットワークを検索し、接続先の候補を提案します。ケーブルで接続したスマートフォンは自動的に表示されます。
3. デバイス画面でデバッグを許可するプロンプトを確認し、「常に許可」にチェックを入れます。 Wi-Fi 接続のスマートフォンでは、代わりに画面に表示されたペアリングコードの入力を求められます。

設定不要のデフォルト動作：ファイルの送受信先は Downloads フォルダー、接続したデバイスは記憶され、adb は自動的に検出されます（またはbrickproof-adb get-adbでダウンロードできます）。

要件

• Node.js 22.17 以降 — Claude Desktop 拡張機能、Home Assistant、Docker 以外のすべてのセットアップで必要です。
• adb（Android SDK Platform-Tools）：Android Studio、WinGet、Homebrew、またはシステムによって配置された場所から自動的に検出されます。またはbrickproof-adb get-adbでダウンロードできます。Docker と Home Assistant には同梱されています。
• USB またはネットワーク経由で接続し、デバッグを有効にしたデバイス。

接続

stdio 経由（Claude Desktop、Claude Code）では、クライアントがサーバーを起動するため、接続作業は不要です。HTTP 経由（brickproof-adb serve）では、トークンをパスまたはヘッダーに指定します。

https://<your-host>/private_<token>/mcp
Authorization: Bearer <token>

トークンは初回起動時に生成されます。brickproof-adb tokenで再表示でき、brickproof-adb token --newで置き換えられます。docs/security.mdをご覧ください。

ツール

18 個のツール。セマンティクス、拒否、制限時間についてはdocs/tools.md、画面のジオメトリと入力についてはdocs/screen-and-input.mdを参照してください。

• adb_devices — 接続済みデバイスと記憶済みデバイス。discover=true を指定するとネットワークを検索します
• adb_connect — ネットワークデバイスに接続します。ip または ip:port を指定します。次回起動時のために記憶されます
• adb_disconnect — ネットワークデバイスを 1 台切断して記憶から削除するか、すべて切断します
• adb_pair — ワイヤレスデバッグ経由で Android 11 以降のデバイスとペアリングします
• adb_shell — 任意のシェルコマンドを実行します。allow_shell を設定するまで無効です
• adb_logcat — 最近のログ行をデバイス上でフィルタリングして取得します
• adb_screenshot — タップ時に使用するスケール情報付きで、画面を JPEG として取得します
• adb_ui_dump — タップ座標付きで画面上の要素を取得します
• adb_tap — 画面座標またはスクリーンショット座標で指定した位置をタップします
• adb_swipe — スワイプまたは長押しを行います
• adb_key — キーを押します（HOME、BACK、DPAD_CENTER など）
• adb_text — フォーカス中のフィールドに入力します。ADBKeyBoard 経由で Unicode に対応します
• adb_find_and_tap — ラベルで要素を探して操作します
• adb_install — APK、分割セット、.apks／.xapk／.apkm バンドルをインストールします。デフォルトではドライランです。パスを指定しない場合は、インストール可能なものを一覧表示します
• adb_uninstall — パッケージ名でアプリを削除します
• adb_app — ガードレール、スナップショット、ロールバックに対応したパッケージ操作を行います
• adb_push — ファイルをデバイスにコピーします
• adb_pull — ファイルをデバイスからコピーします

安全性

デバイスを保護するものと、保護しないものについてはdocs/safety.mdを参照してください。概要は、デフォルトでドライランを行うこと、デバイスから読み取った保護対象リスト、稼働中のサービスに対するネットワークガード、バッチ間のアカウントカナリア、ワンコールでロールバックできるスナップショット、そして有効にするまで無効になっている adb_shell とアンインストールです。これらの切り替えを変更できるツールはありません。変更するのはユーザー自身です。brickproof-adb set を使うか、アプリの設定で変更してください。

制限事項

• ADB はサンドボックスではありません。allow_shell を有効にすると、adb_shell はあらゆるガードを迂回して、デバイスのシェルユーザーにできることを何でも実行できます。
• 検索で見つかるのは同じネットワーク上のデバイスのみです。ゲストネットワーク、Wi-Fi クライアント分離、別の VLAN ではデバイスが見つかりません。Docker と Home Assistant では、ポート 5555 上の TV ボックスのみが見つかります。スマートフォンは画面に表示されているアドレスで接続します。
• ツール一覧はチャットごとにキャッシュされます。更新後は新しいチャットを開始してください。
• スリープ中のデバイスのスクリーンショットは暗い画面になり、応答には screen: Asleep と表示されます。adb_key key=WAKEUP で復帰でき、その後 HDMI-CEC によってテレビの電源が入る場合があります。
• FLAG_SECURE で保護されたコンテンツ（ストリーミングプレーヤー、銀行アプリなど）は黒い画面として表示されます。
• スナップショットは作成したマシン上に保存されます。ロールバックは変更を行った場所で実行する必要があります。
• Docker 内の USB デバイスは Linux ホストでのみ動作します。

ライセンス

MIT