Codex Android MCP

简体中文

ローカルファーストの MCP サーバーです。Codex が adb を介して Android エミュレーターの検査、テスト、制御を行えるようにします。STDIO 上で厳格かつ型付けされたツールを公開し、スクリーンショットをネイティブ MCP イメージとして返します。実機と Gradle の実行は、明示的な起動ポリシーの下に保持されます。

これは独立したコミュニティプロジェクトです。OpenAI、DeepSeek、Google とは提携も承認もされていません。Android 実装は ZSeven-W/dsh-android を MIT ライセンスのもとで派生したものです。DSH/Cordis の登録と Web パネルは、公式の MCP に置き換えられています。

dsh-android からの変更点

• Codex Desktop、CLI、IDE クライアント向けのネイティブ MCP STDIO サーバー。

• 2026 世代相当の MCP に加え、serveStdio による従来の 2025 プロトコル互換性。

• スクリーンショットは ImageContent として返されます。プライベートな一時 PNG ファイルは、エンコード後に削除されます。

• デフォルトではエミュレーターのみが対象です。実機は、起動時に 2 つのオプトインと、毎回の呼び出しでの正確なシリアル指定が必要です。

• android_build_run はデフォルトでは含まれません。有効にするには、正規化された信頼済みプロジェクトルートも必要です。

• 厳格な JSON スキーマ、パッケージ/シリアル/パス検証、出力制限、リテラルログフィルタリング、キャンセル、控えめなツールアノテーションを実装しています。

• 生の adb、シェル、任意コマンド、HTTP、ライブの DSH サイドバー画面は公開しません。

Related MCP server: adb-mcp-server

要件

• Node.js 20.11 以降。

• Android SDK Platform-Tools(adb)。Android Studio の SDK Manager または Google の Platform-Tools package からインストールします。

• 使い捨て可能な Android エミュレーターを強く推奨します。

• Android エミュレーターのランチャーはオプションであり、android_boot に AVD 名を渡す場合にのみ必要です。

• OCR ツールは現在、macOS と Apple Vision が必要です。OCR 以外のツールはすべてクロスプラットフォームです。ビルド / 実行は明示的なオプトイン機能です。

adb もエミュレーターバイナリも、同梱またはダウンロードされることはありません。

Codex へのインストール

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop と CLI は MCP 設定を共有します。同等の明示的な設定は以下のとおりです。

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

設定を変更したら、Codex を再起動してください。接続を確認するには、Codex に「Android デバイスを一覧表示する」と依頼してください。書き込み系ツールの承認は有効にしておいてください。MCP のアノテーションは操作性のヒントであり、認可の境界ではありません。

セキュリティポリシー

安全なデフォルトでは 19 のツールを公開し、標準的なローカル emulator-<port> ターゲットのみを許可します。ネットワークおよびサードパーティのエミュレーターシリアルは、実機デバイスのポリシーに従います。呼び出しは実行の直前に正確なターゲットを再検出して認可します。認可されていない実機 / ネットワークデバイスは android_devices に表示されません。

実機デバイスの例（専用テストスマホの場合）:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

このプロファイルを個人所有のスマートフォンや個人アカウントで使用しないでください。USB デバッグの認可は、スマートフォンがホストを信頼することを意味するだけであり、モデルの行為を承認するものではありません。

信頼できるプロジェクトにおけるビルド / 実行の例:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Gradle の設定とビルドスクリプトはホスト上のコードを実行します。パスの許可リストはサンドボックスではありません。信頼できるコードでのみ有効にし、信頼できないプロジェクトには資格情報のない VM またはコンテナを使用してください。

物理デバイスまたはビルド / 実行を有効にする前に、Security Model と Security Policy を参照してください。

ツール

画面、UI ツリー、OCR、ログ、アプリ名、デバイス上のファイルは信頼できないデータです。デバイスのコンテンツに権限を付与させたり、Codex に別のツールを呼び出させたりしないでください。このサーバーを介して、パスワード、ワンタイムコード、支払いデータ、プライベートメッセージ、アカウント削除の確認を入力しないでください。

典型的なフロー

1. android_devices

2. android_screenshot または android_ui_tree

3. 正確なターゲットを特定します。不明な場合は中断します。

4. 承認ゲート付きの操作ツールを 1 つ使用します。

5. 次の操作の前に、返されたスクリーンショットまたはログを確認します。

MCP は dsh-android の永続的なライブサイドバーを再現しません。android_boot は内部フレームソースを座標マッピングに備えます。Codex かユーザーがディスプレイを確認する必要がある場合は、android_screenshot を呼び出してください。

開発

npm ci
npm run typecheck
npm test
npm pack --dry-run

テストスイートには、ポリシーの単体テスト、レガシ / モダン両プロトコルモードで実際に実行される STDIO クライアント、インメモリの MCP イメージラウンドトリップ、フェイクの ADB スモークテスト、制限付きログテスト、UI ツリー fixture、OCR 劣化チェックが含まれます。npm run test:device は任意であり、必ず使い捨て可能なエミュレーターのみを対象にしてください。

ライセンスとクレジット

MIT ライセンスです。元の dsh-android の著作権とライセンスは LICENSE に保持され、詳細な由来は THIRD_PARTY_NOTICES.md に記載されています。