adb-mcp: Android emulator and device control over adb

---

AVD の起動、スクリーンショットの撮影、UI 階層の読み取り、タップ／スワイプ／入力、デバイスロックの設定、logcat の読み取り、Gradle ビルドとテストの実行ができます。Claude Code、Cursor、VS Code、または stdio 経由の任意の MCP クライアントから、80 個のツールを利用できます。

公式の Go MCP SDK を基盤に構築された、XcodeBuildMCP の Android 版です。

Android は Google LLC の商標です。adb-mcp は Android 向けに開発された独立した非公式ツールであり、Google とは提携、支援、承認の関係にありません。 上記の Android ロボットは、Google が作成して共有した作品を複製／改変したもので、 Creative Commons 3.0 Attribution License に記載された条件に従って使用しています。

このツールを使う理由

Android を手動で操作するには、adb コマンドを並べた長い手順書が必要で、間違いも起こりがちです（古いタップ座標、CRLF によるスクリーンショットの破損、exec-out の指定忘れ、縮小画像からの座標推測など）。このサーバーは、こうした知識をツールに組み込んでいるため、エージェントが覚え直す必要はありません。

• スクリーンショットには exec-out screencap を使用するため、CRLF による破損がなく、画像リーダーが受け取れるよう自動で縮小されます。
• describe_ui は各要素のデバイス上の実際のピクセル単位での中心座標を返します（画像から推測しなくても、狙った場所をタップできます）。また、一時的に発生する「could not get idle state」エラーを自動で再試行します。

ワークフロー自体は、エージェントがタスクの途中で参照できる、読みやすいリソースとして提供されます（観察→操作のループ、ネイティブの PIN／ロック処理、クラッシュの初期調査については後述）。セッションごとに覚え直す必要はありません。

はじめに

1. 前提条件

• platform-tools（adb）と emulator を含む Android SDK。サーバーは $ANDROID_HOME／$ANDROID_SDK_ROOT 経由で SDK を検出し、それらが設定されていない場合はプラットフォームの既定の場所を使用します（macOS では ~/Library/Android/sdk）。MCP クライアントがこれらを設定せずにサーバーを起動する場合は、クライアント設定の args に --sdk /path/to/sdk を渡してください（サーバーが SDK をエクスポートするため、Gradle からも SDK を見つけられます）。doctor で解決された場所を確認できます。
• AVD が 1 つ以上あること（Android Studio の Device Manager で作成してください）。

Go は不要です。リリースにはビルド済みバイナリが含まれており、Go が必要なのはソースからビルドする場合のみです。

2. インストール

macOS/Linux の場合：

curl -fsSL https://raw.githubusercontent.com/iksnerd/adb-mcp/main/install.sh | sh

スクリプト（install.sh）は、お使いの OS／アーキテクチャに適したアーカイブを選択し、リリースの checksums.txt と照合して SHA-256 を検証したうえで、~/.local/bin にインストールします（BIN_DIR=... で変更できます。VERSION=v0.24.3 でバージョンを固定できます）。

バイナリを自分で取得しますか？各プラットフォーム（macOS、Linux、Windows、amd64、arm64）用のアーカイブはリリースページにあり、それぞれのチェックサムは checksums.txt に記載されています。Windows の場合は、windows_amd64 または windows_arm64 の zip をダウンロードし、adb-mcp.exe を PATH 上の任意の場所に配置してください。

インストール後は、組み込みのアップデーターで最新の状態を保てます。最新リリースを取得し、チェックサムを検証してから、バイナリをその場で置き換えます。

adb-mcp update

以下の登録では、サーバーを adb-mcp という名前だけで起動するため、$PATH 上にある必要があります（which adb-mcp でパスが表示されることを確認してください。インストーラーは ~/.local/bin が PATH に含まれていない場合に警告します）。そうでない場合は、代わりにバイナリの絶対パスをクライアントに指定してください。

3. MCP クライアントへの登録

Claude Code：

claude mcp add adb -- adb-mcp

（このリポジトリ内で作業する場合は、同梱の .mcp.json が自動的に読み込まれるため、登録は不要です。）

または、プラグインとしてインストールすると、サーバーが登録され、各操作ガイドに対応するスキルが追加されます。

claude plugin marketplace add iksnerd/adb-mcp
claude plugin install adb-mcp@adb-mcp

Codex 向けには、同じプラグインが Codex のマニフェスト形式で提供されています。

codex plugin marketplace add iksnerd/adb-mcp
codex plugin add adb-mcp@adb-mcp-plugins

Claude プラグインは node でサーバーを起動します。初回実行時に GitHub のリリースからお使いのマシン向けのビルドをダウンロードし、固定された SHA-256 と照合するため、PATH 上に Node が必要ですが、手順 2 は不要です。Codex プラグインでは、手順 2 で PATH 上に配置した adb-mcp が引き続き必要です。プラグインが実行し、送信する内容についてはdocs/PRIVACY.mdを参照してください。

Cursor / VS Code：ワンクリックでインストールできます（手順 2 で adb-mcp が PATH 上に配置されていることが前提です）。

その他のクライアント（Windsurf、Codex、…）：adb-mcp を stdio 経由で実行してください。 一般的な設定形式は次のとおりです。

{
  "mcpServers": {
    "adb": { "command": "adb-mcp" }
  }
}

正しく接続されていることを確認するには、エージェントに「エミュレーターを起動してスクリーンショットを撮って」と頼んでください。

ソースから（Go 1.26 以降）

モジュールでは toolchain go1.26.10 が指定されています。Go 1.26 をインストールすると、初回ビルド時にそのパッチバージョンが自動的にダウンロードされます。

make install                 # builds ./bin/adb-mcp and copies it to ~/.local/bin
# or:
go build -o bin/adb-mcp ./cmd/adb-mcp
# or straight from the module (note the /cmd/adb-mcp suffix):
go install github.com/iksnerd/adb-mcp/cmd/adb-mcp@latest

ツール

10 分野にわたる 80 個のツールがあります。デバイスを操作するすべてのツールでは、serial（adb の -s）を省略可能です。接続されているデバイスが 1 台なら省略し、複数台なら list_devices で取得した値を渡します。詳しいリファレンスは docs/TOOLS.md をご覧ください。

• エミュレーター／デバイス：起動、一覧表示、起動完了待ち、シャットダウン、Wi-Fi 経由での接続、adb_reverse によるポート転送（Metro！）
• 観察：確認用の screenshot（マルチディスプレイ対応の折りたたみ式端末でも動作し、display でパネルを選択できます）、実ピクセル座標で要素の中心を取得する describe_ui（フォーカス中の最前面ウィンドウを対象とし、生体認証プロンプトや、対象を覆い隠す別のアプリを見つけられます。任意の package を指定できます）、filter／query／compact モード、そして要素が存在しないことを信頼できるようにする非表示ノード数。render_stats は実際のビュー階層とフレームの状態をカウントします。ビューポート内のみを対象とする describe_ui では取得できない情報です
• 操作：タップ、tap_on_text／tap_element（ID を指定）、スワイプ、ドラッグ、長押し、文字入力、キーの組み合わせ、PIN パッド、wait、run_sequence（手順とガードを 1 回の呼び出しでまとめて実行します。手順ごとの往復による影響を避け、ネイティブタイマーを使うフローを安定して実行できます）。オプトインの verify_change で、タップやキー入力によって UI が実際に変化したかを確認できます。tap_on_text／tap_element のオプトイン via_accessibility（実験的機能）を使うと、座標タップでは届かないネイティブビューに対して、実際のアクセシビリティクリックを実行できます。bridge/README.md をご覧ください
• ロック／Keystore／生体認証：安全なロック画面の設定／解除、ロック状態の確認、has_biometric_enrolled ＋ fingerprint_touch／finger_remove によるエミュレーター上の BiometricPrompt への応答
• 拡張コントロール（エミュレーター）：send_sms（OTP／2FA）、phone_call、set_battery（dumpsys 経由で実機でも動作）、cellular（ローミング／弱い電波／速度制限）、set_sensor（加速度／光など）、rotate_screen、avd_snapshot。describe_ui からは見えない、エミュレーターのコンソール専用パネルを操作します
• アプリのライフサイクル：インストール／アンインストール、起動／停止、get_app_details（インストール済みアプリのバージョンとランチャーアクティビティ、またはデバイスなしで apk_path を使って指定したローカル APK の情報を取得）、app_state（実行中の PID と Metro バンドルか埋め込みバンドルかを表示）、launch_dev_client（Expo の開発ビルドから Metro を起動し、Dev Launcher をスキップ）、reload_app／open_dev_menu、データの消去、権限、ディープリンク、ファイルのプッシュ／プル
• ログとキャプチャ：1 回限りまたはストリーミングの logcat（部分文字列／優先度／タグによるフィルター、since による時間範囲指定、出力前にトークン／パスワード／API キーをマスクするオプトインの redact）、clear_logcat、last_crash、画面録画
• 環境と診断：ダークモード、位置情報のモック、ステータスバーのクリーンアップ、stay_awake（スリープしやすい画面がスクリーンショット取得中に消灯するのを防止）、doctor
• Gradle ビルドとテスト：assembleDebug、ユニットテスト、インストルメンテーションテスト、JaCoCo による JVM ユニットテストのカバレッジ（get_coverage_report／get_file_coverage）、タスク／バリアント／モジュールの検出（list_gradle_variants／list_gradle_projects）、scaffold_android_project、1 回の呼び出しでビルドして実行する build_and_run。ビルド結果には簡潔な概要（ステータス、エラー数、最初のエラー、APK）が含まれ、すべてのログはマスク処理後にディスクへ保存されます。また、gradle_build background=true と build_status を使うと、数分かかるビルド中に呼び出しを開いたままにせずに済みます
• セッションのデフォルト：session_set_defaults で project_dir／serial を一度設定しておけば、複数モジュール／複数フレーバーのプロジェクトや複数デバイスのセッションで、呼び出しのたびに指定する必要がありません

操作のノウハウは 6 つの MCP リソース（android://guide/*）として提供されており、クライアントは一覧表示して読み込めます。URI は docs/TOOLS.md をご覧ください。以下の基本的なループについては、android://guide/driving を直接参照してください。

基本的なループ

観察 → 特定 → 操作 → 再観察。 状態を見るには screenshot、実ピクセル座標で要素の中心を取得するには describe_ui を使います。tap／tap_on_text／swipe／input_text で操作した後、もう一度 screenshot を撮って確認します。ループ全体と、手戻りを招く注意点については android://guide/driving をお読みください。

開発

make check     # go vet + go test + doc-count check (unit tests need no emulator)
make run       # run over stdio for manual JSON-RPC poking

構成：

cmd/adb-mcp/main.go        entry: subcommands (update/version) or serve MCP over stdio
internal/tools/            thin MCP tool bindings
internal/adb/              the device layer: an adb.Client whose methods are the commands
internal/gradle/           host-side Gradle: builds (summary, log, background jobs), secret redaction, test and coverage reports
internal/uiauto/           pure uiautomator-hierarchy model + parsing (unit-tested)
internal/sdk/              resolves the Android SDK (adb/emulator paths, PATH env)
internal/concurrent/       RunAll/RunIndexed: fan out independent I/O calls, join, done
internal/guides/           the skill guides, embedded and served as MCP resources
internal/selfupdate/       the `adb-mcp update` release fetch/verify/swap
internal/bridgeupdate/     the `adb-mcp bridge install` release fetch/verify/install

依存関係は内向きのみです（tools → adb, gradle, uiauto → sdk）。各 internal/tools/<domain>.go アダプターは、同じ名前の実行ファイルを反映します（デバイスコマンドはadb.Clientのメソッドです）。全体図、パッケージグラフ、ツールの追加ルールについては、ARCHITECTURE.mdを参照してください。

ドキュメント

• adb-mcp.com：ランディングページ
• docs/TOOLS.md：ツールごとの完全なリファレンスとガイドリソース
• ARCHITECTURE.md：反映の規約、パッケージ構成、ツールの追加方法
• docs/CHANGELOG.md：リリース済みの作業、新しい順
• docs/BACKLOG.md：未対応のアイデアとXcodeBuildMCPとの機能差

コントリビューション

セットアップと規約については、CONTRIBUTING.mdを参照してください。セキュリティ上の問題を見つけた場合は、公開のイシューを作成せず、SECURITY.mdを参照してください。MITライセンスです。