NexusAndroid

NexusAndroid

プレーンな ADB を使った、AI エージェント向けの Android 操作機能です。 1 つの MCP サーバー nexus-android で、Claude Code、Codex、 Antigravity から実機の Android スマートフォンを確認して操作できます。画面と UI ツリー、ジェスチャー、アクセント文字や絵文字の入力、 SMS/RCS の読み取り、返信の準備、通知、ファイル、設定に対応しています。root 化も、スマートフォンへのアプリのインストールも、クラウド経由の中継も不要です。USB ケーブルまたはローカル Wi-Fi で接続できます。

Windows PC を使用し、Samsung Galaxy Fold（SM-F971B、One UI）で開発とテストを行いました。USB デバッグに対応した他の Android スマートフォンでも動作するはずですが、未テストです（互換性をご覧ください）。クライアントに送信される内容はすべて英語です。サーバーの指示、ツールの説明、ツールからの報告（結果、拒否、エラー）が含まれます。 Nexus ファミリーの一部です。NexusWindows （Claude · Codex · Antigravity）、 NexusBrowser（リポジトリ）、 NexusAndroid（リポジトリ）。 プロジェクトページ：julienpiron.fr/nexusandroid。

クイックスタート

Windows なら、事前知識なしで約 10 分です。サーバーが PC 上の adb を探すか、Google 公式の Platform Tools を自動でダウンロードします。

1. uv をインストールする（サーバーを実行し、Python を取得します）：PowerShell を開いて実行します。

   winget install --id astral-sh.uv -e
   

   （Windows 標準のパッケージマネージャーです。その他の方法は uv のインストールガイドをご覧ください。）PowerShell を閉じて、新しく開きます。

2. セットアップを実行する（PC ごとに 1 回）：

   uvx nexus-android setup
   

   不足しているものをダウンロードし、検出した AI アプリ（Claude Code、Claude Desktop、Codex、 Antigravity）にサーバーを登録します（既存の設定は保持され、編集するファイルは事前にバックアップされます）。その後、スマートフォンの接続手順を案内し、応答を待ちます。

   • スマートフォンで、［設定］>［端末情報］（Samsung の場合：>［ソフトウェア情報］）>［ビルド番号］を 7 回タップします。
   • ［設定］>［開発者向けオプション］>［USB デバッグ］をオンにします （Android ガイド）。
   • USB データケーブルでスマートフォンを接続し、［USB デバッグを許可しますか？］で許可します（［常に許可］にチェックを入れます）。

   スマートフォンが接続され、すべての AI アプリの設定が完了すると、Ready. と表示されます。そうでない場合は、未完了の項目が表示されます。スマートフォンを接続しても検出されない場合は、メーカー提供の USB ドライバーをインストールしてください （Samsung）。

3. AI アプリを再起動します。 手動で登録する場合：

   • VS Code または Cursor：このページ上部の Install ボタンを使用します。
   • Claude Desktop：nexus-android.mcpb をダウンロードして開きます（［設定］>［拡張機能］）。
   • Claude Code：claude mcp add nexus-android --scope user -- uvx nexus-android （Nexus パック全体を使う場合：/plugin marketplace add pironjulien/nexus-plugins を実行し、続けて /plugin install nexus-android@nexus-plugins を実行します。）
   • Codex：codex mcp add nexus-android -- uvx nexus-android を実行します。
   • Antigravity：エージェントパネルの ⋯ > MCP Servers > Manage MCP Servers > View raw config を開き、下記の nexus-android エントリーを "mcpServers" 内に追加して保存します。

次に AI に、*「スマートフォンを見て、画面に何が表示されているか教えてください。」*と尋ねます。

[mcp_servers.nexus-android]
command = "uvx"
args = ["nexus-android"]

{
  "mcpServers": {
    "nexus-android": {
      "command": "uvx",
      "args": ["nexus-android"]
    }
  }
}

setup のオプション：--no-wait（登録して adb を取得します。スマートフォンは待ちません）、--no-register（AI アプリには変更を加えません）、--apps claude-code,codex（指定した AI アプリのみ：claude-code、claude-desktop、codex、antigravity。 パックは -Only／-Skip の選択を NEXUS_PACK_TARGETS として渡します。名前は同じです。設定されていて空の場合：AI アプリなし）。終了コード：すべて準備完了なら 0、adb またはスマートフォンの準備ができていない場合は 1、AI アプリが未設定の場合は 2、その両方の場合は 3。Nexus パックは NEXUS_PACK=1 を付けて実行します。この場合、質問や待機は行わず、成功時の終了コードは 0 で、最終行に NEXUS_PACK_RESULT Claude Desktop=declared; Codex=declared; Antigravity=plugin が表示されます。Antigravity では、サーバーはプラグインとして追加されます（~/.gemini/config/plugins/nexus-android：サーバーとエージェントガイド）。グローバルエントリーとして追加されることはありません。 アップデート。 AI アプリはバージョンを指定せずに uvx nexus-android を実行します。オフラインでは、uv はキャッシュ済みのバージョンを使用します。起動時にバックグラウンドで、1 日に最大 1 回、サーバーは PyPI に最新バージョンを問い合わせます。新しいバージョンがあり、サーバーが uvx から起動されている場合は、uv のキャッシュに準備します（uvx nexus-android@latest）。このバージョンは、AI アプリを次回起動したときに使用されます。サーバー自身の Platform Tools も同じ方法で更新されます（インストール済みの adb には一切触れません）。setup で 0.11 から 0.12.1 をインストールした場合、宣言には引き続きバージョンが記載されています。切り替えるには、uvx nexus-android setup を 1 回実行してください。状態は Nexus アプリ用に ~/.nexus/status/android.json（product、version、latest、state、checked_at、message）に保存されます。Claude Desktop 拡張機能と install.ps1 は、再インストールするまでバージョンが固定されます。バージョンを固定し、NEXUS_ANDROID_MANAGED を設定するプラグインも同様です（状態には、誰が更新するかが記載されます）。NEXUS_ANDROID_UPDATE=0 を設定すると、チェックが無効になります。

PC でスマートフォンを表示。 uvx nexus-android mirror は、サーバーと同じ adb を使って scrcpy を開きます（1 回インストールしてください：winget install Genymobile.scrcpy）。これにより、別バージョンの adb が 2 つ目に起動してエージェントとの接続が切れることを防げます。オプションは scrcpy に渡されます（複数のスマートフォンがある場合は mirror --turn-screen-off、mirror -s SERIAL）。NEXUS_ANDROID_SCRCPY には scrcpy のフルパスを指定します。スマートフォンにはアプリをインストールしません。ジェスチャー操作と同様に、scrcpy は小さなサーバーを /data/local/tmp にコピーするだけです。

adb は次の順序で検索されます：NEXUS_ANDROID_ADB（フルパス）、PATH、winget の Platform Tools、Android SDK（ANDROID_HOME、Android Studio の既定フォルダー）、その後 ~/.nexus/nexus-android/tools/platform-tools。どれも見つからない場合、サーバーは Google の SDK リポジトリ（dl.google.com、sdkmanager が読み取るマニフェスト）から、このシステム用の最新の安定版 Platform Tools をダウンロードし、Google が公開しているアーカイブのサイズと SHA-1 を確認して、そこに展開します。これを使用することで、 Android SDK 利用規約に同意したものとみなされます。NEXUS_ANDROID_ADB_DOWNLOAD=0 を設定すると、これが無効になります。 アクセント記号付き文字や絵文字の入力には、scrcpy サーバー（Genymobile、Apache 2.0、バージョン 5.0.1 に固定）が必要です。エージェントがそのようなテキストを初めて入力するとき、サーバーは GitHub の scrcpy 公式リリースからダウンロードし、コードに記載された値と照合して SHA-256 を確認したうえで、~/.nexus/nexus-android/tools に保存します（install.ps1 は事前にこれを取得します）。ダウンロードできない場合（オフライン、プロキシなど）、ファイルの配置場所を示すメッセージとともに、アクセント記号付きテキストの入力を拒否します。別のテキストに置き換えることはありません。ASCII 文字はこれがなくても入力できます。

プロンプトの例

• 「Google マップを開いて、最寄りの薬局までのナビを開始して。」
• 「Alice から届いた最新の SMS を読んで、10 分遅れると返信する文面を作成して。」（下書きのみ作成し、「はい」と指示されない限り送信しません）
• 「おやすみモードをオンにして、明るさを下げて。」
• 「スマートフォンから最新の写真を 3 枚、PC に取り込んで。」
• 「バッテリー、ストレージ、セキュリティパッチ、ストア外からインストールされたアプリを確認して。」

仕組み

flowchart LR
    A["Claude Code"] --> S
    B["Codex"] --> S
    C["Antigravity"] --> S
    S["nexus-android<br/>MCP server (Python)"] -->|"ADB over USB or local Wi-Fi"| P["Android phone<br/>(no app, no root)"]
    S -.->|"shared lock, screen-awake state"| L[("~/.nexus")]

look は番号付きの UI ツリーを返します。まずテキストを返し、読み取れるものがない場合、またはリクエストされた場合にのみスクリーンショットを返します。act はジェスチャーをまとめて実行し、各操作の前に画面を読み直して、実際に起きたことを報告します。メッセージ、通知、連絡先、設定は、画面をスクレイピングするのではなく、Android 独自のプロバイダーと dumpsys を通じて読み取ります。

共通サーバーを使う理由

各エージェントにはそれぞれ独自のデスクトップ操作機能がありますが、3 つのクライアントのいずれにも、スマートフォン用のツールは組み込まれていません。サーバーを 1 つにすることで、同じ ADB アクセスを 3 回管理する必要がなくなり、3 つのエージェントが 1 つのロック、画面を点灯した状態に保つセッション、および同じ安全対策を共有できます。

ツール

Google Messages は、MMS と同様に RCS メッセージを Android のメッセージプロバイダーに保存するため、サーバーは画面を介さずに読み取れます。RCS のグループには、そこではエンコードされたアドレスしかありません。サーバーはメンバーを特定し、受信した各メッセージの送信者名を表示します。Google Messages でアーカイブまたはゴミ箱に移動した会話も引き続き読み取り可能で、アプリ内で非表示として表示されます。

読み取りは高速です。adb shell content query を実行するたびにスマートフォン上で Java プロセスが起動するため（約 1 秒）、初回の読み取り時にサーバーは 20 KB のヘルパー（phone/NexusQuery.java、nexus-query.dex にビルド済み）を /data/local/tmp に転送し、scrcpy と同様にシェルの ID で app_process を使って一度だけ起動します。アプリのインストールは不要で、ADB 以外の権限も必要ありません。Android 標準の content コマンドと同じ方法で、プロバイダーに読み取り専用（query のみ）で問い合わせ、行をそれぞれ長さ付きの値として独自にシリアライズするため、メッセージテキストが別の行として扱われることはありません。起動するたびにランダムなトークンが生成され、それがソケット名に含まれ、すべての応答で返されます。これ以外のサーバーからの要求は拒否されます。シェルまたは root ユーザー（カーネルが確認する adbd）からの接続にのみ応答し、要求がない状態が 10 分続くと停止します。ヘルパーを実行できない場合は、同じ結果になるよう adb shell による読み取りにフォールバックします。その場合、行番号または行数が、同じ読み取りを _id に絞った結果と一致しない読み取りは、表示せずに拒否されます。

同じヘルパーで画面も読み取ります。1 つのアクセシビリティ接続（uiautomator dump が呼び出しのたびに開始して終了する UiAutomation）を開いて維持するため、look は UI ツリー、スクリーンショット（スマートフォン上で作成する JPEG）、画面の状態を一度のやり取りで取得します。読み取り専用であり（ジェスチャー、グローバルアクション、文字入力は行いません）、ユーザー自身のアクセシビリティサービスは動作したままです。Android では、この接続は一度に 1 つしか許可されません。ヘルパーはすべてのエージェントで共有され、uiautomator dump にフォールバックする前、画面を 45 秒間読み取らなかった後、または保護対象（銀行や本人確認）のアプリを読み取った直後に接続を返すため、ほかのツール（Appium、uiautomator2）も利用できます。要素の一覧、その番号付け、コードのマスキング、拒否ルールは uiautomator dump と同じです。

パフォーマンス

Samsung Galaxy Fold で測定：メッセージは共有デーモン経由の USB、その他の行は Wi-Fi 経由です。

安全措置

外部に対する操作の脅威モデル（送信、発信、支払い、公開、転送）：エージェントは、ユーザーが承認したものと異なる外部操作を決して実行できてはなりません。承認された操作には、ひとつの正規の識別情報があります。それは、フォアグラウンドアプリ、UI ツリーの要素がドキュメント順に示す内容（テキスト、またはマスクされている場合は生テキストのキー付きシール。正確な位置は含まれないため、4 ピクセルのずれやキーボードの表示で無効にはなりません）、およびジェスチャーの完全な対象（タップを受け取る要素と、そのリソース ID、境界ボックス、描画順、タップ位置、スワイプの開始点と終了点、スクロールの方向、キー入力時にフォーカスされているフィールド）です。この契約は各物理入力の境界で適用されます。すべてのタップ（ダブルタップの各タップを含み、画面が落ち着くのを待たない素早い読み取りでは、2 回目のタップを行わない場合もあります）、スクロールの各スワイプ（指が着地した場所と、そこで何を作動させるかに基づいて判定）、各送信キー（それぞれ単独のステップ）は、それぞれの直前に行った画面の新たな読み取りに基づいて判定され、承認済みの識別情報と照合されます。差異があれば拒否されます。トークンはその識別情報のみに紐付けられ、読みやすい概要（宛先、内容、添付ファイル）とともに表示されます。スワイプやドラッグは、始点と終点の両方についてひとつの読み取りに基づいて判定されます。type はフォーカスのある編集可能なフィールドにのみ入力し、制御文字（改行、タブ）はキーとしてではなく、テキストとして貼り付けます。UI ツリーで説明されていないもの（OCR でしか見つからない対象、対象や宛先に重なる描画面、ヘッダーにツリー上のテキストがない描画面）は、同意の対象に含めません。そのような外部操作は拒否され、ユーザー自身が実行します。送信ボタンの横にある動画や写真のプレビュー、およびツリーで説明されている宛先は、妨げになりません。制限について率直に述べると、最後の読み取りから ADB による入力までのわずか数ミリ秒の間に画面が変化した場合、ADB ツールでは検知できません。

• 支払い、送金、発信、公開、完全削除、書式設定、アンインストール、リセット、サブスクリプションのキャンセル、リポジトリの公開：この種のボタンは、confirm=true がないと拒否されます。タップ、入力、消去、スワイプ、x,y 座標を含め、ボタンを対象とするあらゆる操作が対象です。エージェントは、その操作についてユーザーから明示的な指示があった場合、またはユーザーが「はい」と答えた後に設定します。ラベルはデスクトップツールと共有するポリシーファイル（garde-fous.json）から取得し、アクセント記号や大文字小文字を区別せず、列挙されたすべての表記（「Envoyez」、「Payez」、「Paiement」、「Commandez」、「Checkout」、「Appeler」など）と照合します。それ以外はすべて自由に操作できます。ゴミ箱への削除、承諾、共有が含まれます。一般的な「OK」や「Validate」は、支払いや書式について説明する画面では、この設定が必要です。メッセージ、メール、ソーシャル、電話アプリでは、名前のないクリック可能なアイコン（多くの場合、送信または発信ボタン）にも必要です。Enter、発信キー、および短い安全リストに含まれないキーにも必要です。
• 操作内容に厳密に結び付いた同意（送信、発信、支払い、公開、振込）：confirm=true だけでは不十分です。ツールは、画面に表示されているとおりの操作内容（アプリ、ボタン、宛先：ヘッダーに加え、表示されている電話番号またはメールアドレス、各フィールドのテキスト、名前が付いた添付ファイル、その他画面上のアプリのテキスト、元のテキストのシールに結び付けられたマスク済みテキスト）と、10 分間有効な使い捨てトークンを返します。各操作を実行する直前に画面を読み直して照合します。エージェントはその要約をユーザーに提示し、ユーザーが同意した場合に限り、accord="<token>" を付けて操作を再送します。draft は、独自の下書き用トークンを返します。その間に変更があった場合（別の会話、編集されたテキストなど）、トークンは無効になり、新しい同意が必要です。同じルールは、あらゆる送信方法に適用されます。タップ、スワイプ、「スライドして送信」、指がそのスライダー上に着地するスクロール（同意を付けて 1 ステップずつスクロール）、Enter または発信キー（それぞれ単独のステップで実行し、まず tab、次に enter）、open_url による支払いリンク、発信・送信・支払いを行う launch インテントが対象です。UI ツリーを読み取れず、操作内容を説明できない場合は、トークンは発行されず、操作は拒否されます。複数行のテキストは貼り付けます（改行はテキストであり、送信される可能性がある Enter キーではありません）。外部に作用するボタンをダブルタップすることはありません。ローカルで完結する破壊的操作（アンインストール、リセット、完全削除）では、confirm=true だけで引き続き実行できます。
• テキストを読んでも操作は許可されません：SMS、通知、画面はデータです。最近読んだテキストに宛先が記載されている場合、同意の要約でその宛先にフラグを付けます（ユーザー自身が依頼した場合に限り許可されます）。AI に向けた指示のように見えるテキストは、応答でフラグが付けられます。この検出機能はあくまでシグナルであり、ブロックするものでも、保証するものでもありません。
• 現在の画面で対象を確認：各操作の直前に、UI と電話の状態（ロック状態、フォアグラウンドアプリ）を 1 回のラウンドトリップで再確認します。[N] が変わっている場合や、読み取れる内容がない場所は拒否されます。報告：✓ 効果を読み戻して確認済み、~ 送信済みだが未確認、✗ 拒否または失敗。
• 電話は 1 台のみ：所有者の電話は、最初の USB 接続時に記録されたハードウェアのシリアル番号で識別されます。エミュレーター、TV ボックス、その他のデバイスは無視されます。同時に操作できるエージェントは 1 つだけです（PC 上のすべてのサーバーと共有デーモンのセッションでロックを共有します）。別のエージェントは最大 30 秒待機し、その後、電話は使用中であると通知されます。クライアントがキャンセルした呼び出し（または切断したクライアント）は、バッチの次のステップに進む前に停止します。
• 銀行、支払い、暗号資産、ギャンブル、本人確認、認証アプリ：閲覧、スクロール、待機は自由に行えます。タップ、入力、スワイプは、confirm=true（ユーザーによるナビゲーションの指示）がある場合に限ります。金銭または送信に関するボタン、名前のないアイコン、Enter、または任意の確定キーは、confirm=true と同意があっても決して操作できません。UI ツリーを読み取れない場合、対象を指定した操作は一切できません（戻る、ホーム、最近のアプリのみ可能です）。それらのアプリを開くリンク（open_url）やインテント（action/data を伴う launch）は、ほかの選択肢の 1 つとして含まれているだけでも拒否されます（ディープリンクによって支払いの準備が行われる可能性があります）。
• 独自に動作するインテントとリンク（CALL、確認なしでテキストを送信する操作、アンインストール、リセット、支払い操作、upi:/bitcoin:/payto: リンク、自動送信エクストラ）：confirm=true に加え、発信、送信、支払いでは、正確なインテントに結び付いた同意が必要です。
• SMS で受信したコードや通知に表示されたコード：エージェントが読む前にマスクされ、画像上でも黒く塗りつぶされます（[N] バッジはその後に描画されます。覆い隠すことはできても、情報を露出させることはありません）。OCR が画像上で検出したコードも、look の画像（ツリーにテキストがない大きな描画面）と保存済みスクリーンショット（ラベルの有無を問わず、すべての大きな描画面）で黒く塗りつぶされます。制限：保存済みスクリーンショットの OCR で対象となるのは、画面の 25 % 以上を占める描画面（またはテキストがまったくないツリー）だけです。それより小さな描画面に表示されたコードは黒く塗りつぶされません。OCR を利用できない場合（Windows 以外）や OCR が失敗した場合でも、look はユーザー自身の電話の画像を返しますが、描画されたコードがマスクされていないことを明確に警告します。保存済みスクリーンショットは、unmasked=true がない限り拒否されます。銀行カード番号（ルーン・アルゴリズムによるチェック）と IBAN（mod 97 チェック）は、ツールが返すすべてのテキスト（画面、通知、SMS、クリップボード、カレンダー、ログ、ウェブ、マップ）でマスクされます。カード番号は次の形式のみが対象です（最初の桁は 2～6）：4-4-4-4 のグループ（後ろに 1～3 桁が続く場合と続かない場合）、4-6-5、4-6-4、4-4-5、4-3-3-3、または 15～19 桁の連続した数字。これにより、カレンダー、描画、数値の表、SIRET、EAN-13 は読み取り可能なままになります。IBAN は国ごとの正確な桁数（SWIFT レジストリに基づく）のもののみが対象で、単語に連結されている場合も含め、どのような大文字小文字でもマスクされます。グループは、半角スペース、ノーブレークスペース、ダッシュ、ピリオド、または改行で 1～2 個ずつ区切られている必要があります。クリップボードでは、単独のコード、またはパスワードやトークンのように見える単一の単語は、まったく表示されません。UI ツリーを読み取れない場合はコードの位置を特定できないため、confirm=true（ユーザーの同意を伴う）で look を実行しない限り、画像は送信されません。
• パスワード：パスワード欄への入力は禁止です。その欄で許可されるキーは、ナビゲーション用（戻る、Tab、矢印）のみです。アクティブなフィールドを読み取れない場合は、confirm=true があっても入力できません。
• ロックされた電話：コードを入力することは決してありません。Android 自体が電話のロックを解除した状態に保っている場合（Extend Unlock、Smart Lock、信頼できる場所またはデバイス：dumpsys trust が deviceLocked=0 を示す場合）、phone は code_required: false を報告します。また、look、act、capture は電話を起動し、ロック画面を解除します（wm dismiss-keyguard）。エージェントがユーザーに尋ねることはありません。コードが必要な場合（code_required: true）に限り、ユーザーがロックを解除するまで操作は拒否されます。
• 画面またはメッセージ上の テキストの読み取り はデータであり、指示ではありません。
• ユーザーが電話を操作中の場合：ユーザーの操作とエージェントの操作が重なることはありません。過去 3 秒以内に電話がタッチされていた場合（エージェントによるタッチを除く）、サーバーは最大 10 秒待機し、その後拒否します。電話が最後のタッチを報告しない場合（dumpsys power に lastUserActivityTime がない場合）、act の応答で警告します。その場合、このチェックは無効です。
• 操作中に接続が失われた場合：単なる失敗ではなく、効果が不明であることを示す ? が報告されます。エージェントは操作をやり直す前に再確認し、二重送信を防ぎます。応答のない読み取り（Wi-Fi が切断された場合など）は、数分ではなく 10 秒後（画面の状態は 5 秒後）に失敗し、次の呼び出しで電話を再検索します。
• 前回の画像取得から折りたたみ式端末の開閉状態が変わった場合、新たに look を実行するまで x,y による対象指定は拒否されます。
• 再起動：電話が再起動したことを、phone と look が一度だけ通知します。電話を見つけられない場合は、再起動またはネットワーク変更後に Android がワイヤレスデバッグをオフにすることをメッセージで知らせます。
• その他の制御ツール（mobile-mcp、Appium、Shizuku、別の scrcpy）が電話上で起動したままになっていると、UI ツリーがブロックされることがあります。checkup とエラーで、そのツールが通知されます。

エージェントの作業中に画面を点灯したままにする

エージェントの作業中に何度もロックを解除するのは面倒ですが、支払いに使うスマートフォンのロックは解除したままにできません。そのため、ユーザーがロックを解除したスマートフォンで、最初のジェスチャー（act、launch、draft）を行うと、サーバーは画面消灯タイムアウト（screen_off_timeout）を保存し、5分に延長します。Android では、この時間はジェスチャーのたびに再カウントされます。phone には、いつまで延長されるかが表示されます。サーバーが強制終了されても、最後のジェスチャーから最大5分後には画面が消灯（およびロック）します。エージェントが画面を見るだけの場合、点灯中の画面には3分ごとにウェイクアップキーが送られるため（画面上の変化はありません）、長時間の確認中に画面が消灯することはありません。

いずれかのエージェントによる最後のジェスチャーから約2分後に、元のタイムアウトが復元され、画面が消灯してスマートフォンが再びロックされます。その時点でユーザーがスマートフォンを持っている場合、またはユーザー自身がタイムアウトを変更した場合は、画面の状態は変更されません。元の値は一度だけ保存され（~\.nexus\nexus-android\awake.json）、共通のロックの下で、すべてのサーバー間で共有されます。保存は一度、復元も一度だけ行われ、延長後の値が元の値として保存されることはありません。クラッシュ後は、次に起動したサーバーが元の値を復元します。Android によってロックされたままのスマートフォンを、サーバーがロック解除することはありません。 NEXUS_ANDROID_AWAKE_IDLE（秒、デフォルトは120）で遅延時間を変更できます。NEXUS_ANDROID_KEEP_AWAKE=0でこの機能を無効にできます。

互換性

スマートフォン側で必要なのはUSBデバッグだけです。ADBが使えるAndroid端末であれば動作するはずですが、ここで実際にテストしたのは一覧にある端末のみです。お使いの端末をissueで報告して、一覧に追加しましょう。

既知の制限事項

• ジェスチャーは意図的に実際の画面上で実行されます。ユーザーはエージェントの動作を確認できます。非表示の仮想ディスプレイはありません。
• アクセント付き文字と絵文字はクリップボード経由で入力されます（Android の input text は ASCII しか受け付けません）。scrcpy サーバー （Genymobile、Apache 2.0、バージョンと SHA-256 を固定。install.ps1 または最初のアクセント付き文字の入力時にダウンロード）は貼り付け中のみ実行され、その後、以前のクリップボードの内容が復元されます。Samsung のクリップボード履歴には、貼り付けたテキストが残る場合があります。
• 通知：Android が保持するのは、閉じた通知のアプリ名のみで、通知テキストは保持しません。
• FLAG_SECURE で保護されたアプリでは、スクリーンショットが黒くなります。サーバーがその旨を伝え、[N] の要素は読み取れる状態のままです。
• Android では、アクセシビリティ自動化クライアントを同時に 1 つしか使用できません。別のツールのサーバー（mobile-mcp、Appium、uiautomator2 など）が使用中の場合、UI ツリーを読み取れません。look にそのツール名と pid が表示されます。ツールを閉じるか停止してから、再試行してください。
• 接続には USB またはワイヤレスデバッグ経由のローカル Wi-Fi を使い、各 PC とペアリングします。ADB は Bluetooth 経由では動作しません。
• Xiaomi、Redmi、POCO（MIUI、HyperOS）では、開発者向けオプションの「USB デバッグ（セキュリティ設定）」をオンにするまで、ジェスチャーの注入が拒否されます。エラーにもその旨が表示されます。
• インストーラー（install.ps1）、test.ps1、OCR は Windows 専用です。Linux ではサーバー自体は動作し、CI でエミュレーターに対してテストされています。macOS はテストされていません。

採用しなかった選択肢

• スマートフォンにコンパニオンアプリをインストールする：通知、アクセント付き文字の入力、ファイル、設定はすべて ADB 自体から取得します。アプリを追加しても、USB と自宅の Wi-Fi 以外から制御できるだけで、その機会はほとんどありません。
• 非表示の画面：エージェントが実際の画面上で動作する様子を見られることは、機能の一部です。
• インターネット経由の中継（トンネル、VPN）：USB またはローカル Wi-Fi のみです。

フルインストール（Windows）

uvx の代わりとなる方法です。1 つのローカル環境を作成し、PC 上で見つかったクライアントに登録します。scrcpy サーバーは事前に取得します。

前提条件：Windows、PowerShell 7、uv。Android Platform Tools は任意です（winget install Google.PlatformTools）。インストールしない場合は、初回使用時にダウンロードされます。スマートフォンでは、開発者向けオプション → USB デバッグを有効にします（nexus-android setup が手順を案内します）。

git clone https://github.com/pironjulien/NexusAndroid
cd NexusAndroid
pwsh -NoProfile -File install.ps1          # environment, scrcpy server, Codex/Antigravity registration, tests
pwsh -NoProfile -File install.ps1 -Live    # plus a run on the connected phone (types then clears a draft SMS, never sends)

スクリプトの動作（たとえば git pull の後など、何度でも安全に実行できます）：

• 環境：~\.nexus\nexus-android\venv。パッケージのコピーを配置します（クローンへのリンクではありません）。
• scrcpy サーバー：公式リリースからダウンロードし、SHA-256 が一致する場合のみ保持します。
• Codex：~\.codex が存在する場合、~\.codex\config.toml に [mcp_servers.nexus-android] テーブルを追加します（stdio、環境の Python を使用）。古い nexus-android テーブルは置き換え、ファイルの他の部分は変更しません。以前のファイルは先に ~\.nexus\nexus-android\backups にコピーされます。
• Antigravity：~\.gemini\antigravity またはその設定ファイルが存在する場合、~\.gemini\config\mcp_config.json に nexus-android エントリーを追加し、同様にバックアップします。
• Claude Code：同じ環境を使用するために実行する claude mcp add コマンドをスクリプトが表示します。Claude CLI 自体を呼び出すことはありません。
• テスト：test.ps1（オフライン、スマートフォン不要）。-SkipTests はテストをスキップし、-NoRegister はクライアントの設定を変更しません。

各クライアントは、その後 stdio 経由で独自のサーバーを起動します。スマートフォンのロックと画面の点灯状態は、各クライアント間で ~\.nexus を通じて共有されます。すべてのクライアントで 1 つのプロセスを共有する方法については、共有デーモンを参照してください。

ケーブル不要の Wi-Fi 接続（PC ごとに 1 回）

1. スマートフォン：設定 → 開発者向けオプション → ワイヤレスデバッグ → ペア設定コードによるデバイスのペア設定。
2. PC：adb pair <ip>:<port> を実行し、スマートフォンに表示されたコードを入力します。

以降、nexus-android はローカル Wi-Fi 上でスマートフォンを検出します。One UI は mDNS でスマートフォンを通知しないため、サーバーは USB 接続するたびに Wi-Fi アドレスとワイヤレスデバッグのポートを記録します。このポートは再起動またはネットワーク変更後に変わるため、その場合は USB で 1 回接続すれば十分です。サーバーは最後に確認されたアドレスを最初に試し、次に mDNS を試します。PC が同じネットワーク上にある場合に限り、サーバーは新しいポートを探し、ADB ハンドシェイクで確認してから接続します。スマートフォンが見つからない場合、サーバーは 2 分間 Wi-Fi を再検索しません（ケーブルが接続されると、すぐに検出されます）。ケーブルが接続されている場合は、ケーブル接続が優先されます。NEXUS_ANDROID_SERIAL を設定すると、シリアル番号または ip:port アドレスで特定のデバイスを指定できます。

共有 Wi-Fi ネットワークがない場合（イーサネットのみ接続されたオフィスの PC に Wi-Fi カードがある場合）：スマートフォンのホットスポットをオンにして PC を接続し、ケーブルを 1 回接続した状態で adb tcpip 5555 を実行します。サーバーはスマートフォンのホットスポットのアドレスを記録し、ケーブルを外した後もそこでスマートフォンを検出します。TCP モードはスマートフォンを再起動するまで（または adb usb を実行するまで）継続します。インターネット通信をスマートフォンのモバイルデータではなくイーサネット経由にしたい場合は、PC の Wi-Fi インターフェースのメトリックを高くしてください。

暗号化されません。 ペアリングされた TLS 接続を使うワイヤレスデバッグとは異なり、adb tcpip 5555 は暗号化されていない TCP 上で動作する従来の ADB です。通信内容にはスクリーンショットやメッセージも含まれ、そのネットワーク上で読み取ることができ、ポートも開いたままになります。スマートフォン自身のホットスポット、または自分が管理する別のネットワークでのみ使用し、使用後は adb usb を実行して無効にしてください。

共有デーモン（任意）

デフォルトでは、各クライアントがそれぞれ独自の nexus-android プロセスを起動します。すべてのクライアントで 1 つのプロセスを実行するには、HTTP モードでサーバーを起動します。

$env:NEXUS_MCP_TOKEN = "<random string, 32 characters or more>"   # or NEXUS_MCP_TOKEN_FILE = path of a file holding it
nexus-android --http 16180

サーバーは 127.0.0.1 のみで MCP Streamable HTTP を提供します（デフォルトポートは 16180）。エンドポイントは http://127.0.0.1:16180/mcp で、Authorization: Bearer <token> ヘッダーがないリクエストはすべて拒否します（HTTP 401）。トークンなしでは起動しません。各クライアントを、この URL とヘッダーを使うように設定してください。各 MCP セッションは独自の [N] 番号と会話リストを持ちますが、ADB 接続とスマートフォンのロックは共有されます。デーモンの起動（たとえばログオン時）はユーザー自身で設定してください。install.ps1 は設定しません。このトークンは、設定ミスのあるクライアントや予期しないセッションによるスマートフォンの操作を防ぎますが、同じ PC 上で動作する悪意のあるソフトウェアに対する保護にはなりません。そのようなソフトウェアは、ADB 経由でスマートフォンに直接アクセスできます（SECURITY.md を参照してください）。

プライバシー

NexusAndroid はすべて PC 上で動作し、ADB（USB ケーブルまたはローカル Wi-Fi）経由でスマートフォンと通信します。アカウント、テレメトリー、アナリティクス、クラウド中継はありません。インターネットへのリクエストに個人やスマートフォンに関するデータが含まれることはありません。リクエストは最大でも 1 日に 1 回の PyPI からの最新バージョン番号の取得と、独自の adb を使用する場合の Google SDK リポジトリマニフェストの取得（NEXUS_ANDROID_UPDATE=0 で無効化）、PC に adb が見つからない場合または独自のものが古い場合の dl.google.com からの Google Platform Tools の取得（NEXUS_ANDROID_ADB_DOWNLOAD=0 で無効化）、アクセント付きテキストを初めて入力するときの GitHub からの固定バージョンの scrcpy サーバーの取得（install.ps1 がすでに取得している場合はスキップ）です。

• 読み取るデータ：画面と UI ツリー、SMS／RCS メッセージ、通知、共有ストレージ内のファイル、位置情報、最近の通話、連絡先、カレンダーです。エージェントが対応するツールを呼び出した場合にのみ読み取ります。セキュリティコードはエージェントに表示される前にマスキングされます。
• データの送信先：ツールの結果は、接続した AI クライアント（Claude、Codex、Antigravity など）に返されます。そのクライアントは独自のプライバシーポリシーに基づいてモデルプロバイダーにデータを送信する場合がありますが、NexusAndroid がほかの場所にデータを送信することはありません。
• PC に保存するデータ：~/.nexus/ 以下に、スマートフォンのマップ（map/：Settings ツリー、map note で記録した画面、設定値、アプリ、権限、Bluetooth デバイス名のスナップショット最大 30 件。識別子、トークン、アドレス、番号はマスキングされます）、スマートフォンのシリアル番号、Wi-Fi アドレスとワイヤレスデバッグポート、保存した画面タイムアウト、ロックファイル、最後にアップデートを確認した日付（update.json）、固定バージョンの scrcpy サーバー、ダウンロードした Platform Tools（adb が見つからなかった場合）、setup または install.ps1 が編集する AI クライアント設定のバックアップ（backups/）、および install.ps1 を使用した場合はその環境が保存されます。pull したファイルは ~/Downloads/Telephone に保存されます。サーバーがメッセージやスクリーンショットをディスクに書き込むことはありません。
• ジャーナル：%LOCALAPPDATA%\NexusJournal\android\<agent>\<YYYY-MM>.jsonl（または NEXUS_JOURNAL_HOME）以下に、Nexus ツール共通形式で保存されます。ジェスチャーまたはツール呼び出しごとに、呼び出した AI（Claude、Codex、Antigravity）、アクション、結果、所要時間、手法、アプリのパッケージ名、固定リストから選ばれたエラーカテゴリを 1 行に記録します。画面上のテキスト、SMS、連絡先、入力したテキスト、コードは記録しません。どこにも送信されません。削除するまで月ごとの記録が保持されます。いつでも android フォルダー（または個別の月別ファイル）を削除できます。サーバーの環境変数に NEXUS_JOURNAL=0 を設定すると無効になります（何も書き込まれず、フォルダーも作成されません）。
• スマートフォン上：/data/local/tmp に 2 つのヘルパー（nexus-scrcpy.jar、nexus-query-*.dex）が残ります。UI ダンプ（nexus-android-ui-*.xml）と一時的な読み取りフォルダー（nexus-q-*、nexus-p-*）は読み取りのたびに直後に削除されます。読み取りヘルパーは、リクエストがない状態が 10 分続くと自動的に停止します。
• 削除方法：~/.nexus/nexus-android/、~/.nexus/android.lock、%LOCALAPPDATA%\NexusJournal\android\ を削除し、各クライアントの設定から nexus-android の項目を削除して、adb shell "rm -rf /data/local/tmp/nexus-*" を実行します（ヘルパー、UI ダンプ、中断された読み取りで残った読み取りフォルダーが削除されます）。また、スマートフォン上で PC のキーを無効にします（開発者向けオプション → USB デバッグの許可を取り消す）。

ご質問や懸念事項がある場合は、issue を開くか、非公開で報告する方法について SECURITY.md をご覧ください。

開発

まず Node.js をインストールしてください。Python とロックファイルで指定されたパッケージがすでにローカルで利用できる状態で、次を実行します。

pwsh -NoProfile -File test.ps1   # ruff, pyright and the unit tests, offline, no phone needed

このチェックでは、Python、パッケージ、Pyright をダウンロードしません。uv はオフラインで実行され、自動の Python ダウンロードは無効化されます。また、Pyright はインストール済みの Node.js を使い、同梱の JavaScript から実行されます。Python がない場合や、依存関係のキャッシュが不完全な場合は、明確なエラーが発生します。各チェックアウトでは、テスト環境をソースツリーの外部に保持します。

新しいマシンの場合、またはロックファイルを変更した後は、オンラインの状態で別途キャッシュを準備してください（CI ではオフラインチェックの前にこれを実行します）。

$env:UV_PROJECT_ENVIRONMENT = Join-Path $env:TEMP 'nexus-android-prepare'
uv sync --frozen --python 3.14  # explicitly online preparation, including development and build dependencies
pwsh -NoProfile -File test.ps1 -Python 3.14

-Python 3.12、3.13、3.14、または3.15を指定すると、インストール済みのインタープリターが選択され、別個のテスト環境が使用されます。-Fullを指定すると、既存の実機スマートフォンを使ったシナリオも実行されます。スマートフォンは接続可能で、ロックが解除されている必要があります。

ライセンス

MIT。Google、Samsung、Anthropic、OpenAI、Genymobile とは提携していません。