android

Android MCP サーバー

Android の診断・フォレンジック向け MCP です。アプリがクラッシュしたり、メモリリークやバッテリー消費が発生したり、予期しない動作をしたりしたときに、デバイスを調べるために使います。

logcat／dumpsys／パッケージ内部情報／システムプロパティ／プロセスに対応する 76 個のツールを備えています。5 つの MCP プロンプト（crash-investigation、memory-leak-detection、permission-audit、app-startup-profile、ui-element-locator）と、device-health の集約機能もあります。純粋な ADB 実装で、Appium／uiautomator2 への依存はありません。2 段階のセキュリティ（書き込みとシェルのゲート）を採用しています。

他のツールにはない機能

• 診断の深さ — logcat の検索とクラッシュ情報の抽出、dumpsys（メモリ／グラフィックス／CPU）、getprop、プロセス、パッケージ内部情報、アプリのインテント、ポートフォワードに対応しています。クロスプラットフォームの競合製品では、こうした機能にアクセスできません。
• MCP プロンプト（5 種類）— crash-investigation、memory-leak-detection、ui-element-locator、app-startup-profile、permission-audit。モデルが直接呼び出すワークフローテンプレートです。
• 集約ツール — device-health（バッテリー＋メモリ＋CPU＋ネットワークを 1 回の呼び出しで取得）、analyze-app（パッケージ情報＋メモリ＋アクティビティ）。
• 2 段階のセキュリティ — ANDROID_MCP_ALLOW_WRITE（インストール／タップ／プッシュを制御）と ANDROID_MCP_ALLOW_SHELL（任意の adb shell を制御）は別々のフラグです。信頼レベルを区別できます。
• 純粋な ADB 実装 — Appium、uiautomator2、Python ブリッジは不要です。child_process を通じて公式の Android Debug Bridge をラップするだけです。
• トークン効率を考慮した設計 — スキーマを 56 回に分けて削減し、ANDROID_TOOLS／ANDROID_DISABLE で 9 つのカテゴリを制御できるほか、search-tools メタツールを備えています。
• Apps SDK カード — device-health は _meta["openai/outputTemplate"] を通じて ChatGPT クライアント上にスナップショットカード（バッテリー、RAM、Wi-Fi＋4 セクションのグリッド）として表示されます。Claude クライアントには同じ JSON コンテンツが返されます。
• stdio＋Streamable HTTP — デフォルトは stdio です。ChatGPT Apps SDK またはリモートクライアントを使う場合は、MCP_TRANSPORT=http を設定します（MCP_HTTP_TOKEN による Bearer 認証）。

試してみましょう — 5 つのプロンプト

サーバーを Claude Desktop または Claude Code に接続し、以下のいずれかを貼り付けてください。

1. クラッシュの調査 — 「Pixel 6 エミュレーターでアプリ com.us-all.api が何度もクラッシュします。直近のクラッシュログ、問題のスタックフレーム、最近の権限変更を取得してください。」
2. メモリリークの検出 — 「過去 5 分間の com.us-all.api のメモリ増加を追跡してください。ヒープの差分、GC の負荷、最大のメモリアロケーターを表示してください。」
3. バッテリー消費の原因特定 — 「このデバイスのバッテリーを消費しているものは何ですか？消費量上位 5 件、それぞれの継続時間、現在のバッテリー状態を教えてください。」
4. 権限の監査 — 「インストール済みのサードパーティ製アプリを監査し、危険な権限（位置情報／カメラ／連絡先／マイク）を確認してください。これらの権限を持ち、過去 30 日間使用されていないアプリにフラグを立ててください。」
5. アプリ起動のプロファイリング — 「com.us-all.api のコールドスタートをプロファイリングしてください。アクティビティの起動時間を測定し、初期化が最も遅いフラグメントを特定して、トレースを追加すべき場所を提案してください。」

これと mobile-next/mobile-mcp の使い分け

mobile-next/mobile-mcp（4.7K★）は、クロスプラットフォーム対応のアクション指向型 MCP です。対象とする課題が異なります。

	mobile-mcp	@us-all/android-mcp（この MCP）
プラットフォーム	iOS + Android（クロスプラットフォーム）	Android のみ（専門特化型）
アプローチ	アクション指向（「自然言語でアプリを操作する」）	診断指向（「何が原因で壊れたのかを調べる」）
UI の確認方法	アクセシビリティツリーを優先し、アクションを繰り返す	UI 階層 + スクリーンショット + 診断ダンプ
診断の深さ	最小限	logcat / dumpsys / getprop / プロセス / クラッシュ
集約機能	—	device-health、analyze-app
MCP プロンプト	—	5 種類（診断向け）
セキュリティゲート	基本	2 段階（書き込みとシェルを個別に制御）
配布方法	幅広く対応（12 以上の IDE ボタン）	npm + Docker

両方を使いましょう。互いに補完し合います。 mobile-mcp は QA ワークフローを通じてデバイスを操作し、この MCP は問題が発生した際に原因を調べます。特に、次のような場面で役立ちます。

• mobile-mcp が UI の探索でバグを見つけたら → この MCP がクラッシュログ + ヒープダンプを取得します。
• mobile-mcp では起動が遅い理由を特定できません → この MCP は dumpsys gfxinfo + アクティビティ起動時間を提示します。
• mobile-mcp では権限拒否を再現できません → この MCP は正確な dumpsys package の権限状態と最近の許可を表示します。

インストール

Claude Desktop

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@us-all/android-mcp"],
      "env": {
        "ANDROID_MCP_ALLOW_WRITE": "true"
      }
    }
  }
}

Claude Code

claude mcp add android -s user \
  -e ANDROID_MCP_ALLOW_WRITE=true \
  -e ANDROID_MCP_ALLOW_SHELL=true \
  -- npx -y @us-all/android-mcp

Docker

docker run --rm \
  --device /dev/bus/usb \
  -e ANDROID_MCP_ALLOW_WRITE=true \
  ghcr.io/us-all/android-mcp-server:latest

ソースからビルド

git clone https://github.com/us-all/android-mcp-server.git
cd android-mcp-server && pnpm install && pnpm build
node dist/index.js

前提条件

• ADB がインストールされ、PATH に設定されていること（または ADB_PATH を設定すること）
• USB デバッグが有効になっている Android デバイスまたはエミュレーター
• 複数のデバイスを使用する場合：特定のデバイスを指定するには ANDROID_SERIAL=<serial> を設定します

設定

変数	必須	デフォルト	説明
ANDROID_HOME	❌	自動検出	Android SDK のパス
ADB_PATH	❌	adb（PATH）	ADB バイナリのパス
ANDROID_SERIAL	❌	自動（デバイスが 1 台の場合）	対象デバイスのシリアル番号
ANDROID_MCP_ALLOW_WRITE	❌	false	書き込み操作（インストール、タップ、プッシュ）を有効にします
ANDROID_MCP_ALLOW_SHELL	❌	false	任意の adb shell 実行を有効にします
ANDROID_TOOLS	❌	—	カテゴリのカンマ区切り許可リスト。トークンを大幅に節約できます。
ANDROID_DISABLE	❌	—	カテゴリのカンマ区切り拒否リスト。ANDROID_TOOLS が設定されている場合は無視されます。
MCP_TRANSPORT	❌	stdio	Streamable HTTP トランスポートを有効にするには http を指定します
MCP_HTTP_TOKEN	条件付き	—	ベアラートークン。MCP_TRANSPORT=http の場合は必須です
MCP_HTTP_PORT	❌	3000	HTTP リッスンポート
MCP_HTTP_HOST	❌	127.0.0.1	HTTP バインドホスト（localhost の場合、DNS リバインディング保護が自動的に有効になります）
MCP_HTTP_SKIP_AUTH	❌	false	ベアラー認証をスキップします（認証を処理するリバースプロキシの背後で使用する場合など）

カテゴリ（9 種類）：device、apps、ui、logcat、emulator、files、system、debug、shell（常に ANDROID_MCP_ALLOW_SHELL による制限を受けます）。これに加えて、常時有効な meta があります。

MCP_TRANSPORT=http の場合：POST /mcp（ベアラー認証付き JSON-RPC）+ GET /health（公開ヘルスチェック）。

トークン効率

シナリオ	ツール数	スキーマのトークン数	デフォルト比
デフォルト（すべてのカテゴリ）	76	9,200	—
一般的な設定（ANDROID_TOOLS=device,ui,apps,logcat）	37	5,000	−46%
絞り込んだ設定（ANDROID_TOOLS=device,ui）	19	2,500	−73%

さらに、実行時にツールを検出するための search-tools メタツールも常時有効です。

読み取り専用モード（デフォルト）

デフォルトでは、読み取り操作のみが許可されます。書き込み操作（tap、install-app、push-file など）は、ANDROID_MCP_ALLOW_WRITE=true を設定しない限りエラーを返します。追加のセキュリティ対策として、シェルコマンドの実行には別途 ANDROID_MCP_ALLOW_SHELL=true が必要です。書き込みを有効にしても、明示的に設定しない限り、直接のシェル実行はブロックされたままです。

MCP プロンプト（5）

MCP の prompts/list から利用できるワークフローテンプレート：

• crash-investigation — 対象パッケージのクラッシュログ、スタックフレーム、最近の権限変更を取得します。
• memory-leak-detection — 期間内のヒープ差分を追跡し、アロケーター別にクラスタリングします。
• ui-element-locator — 視覚情報とアクセシビリティ情報を手掛かりに UI 要素を見つけ、タップ座標を返します。
• app-startup-profile — コールドスタートのプロファイル：アクティビティの起動、フラグメントの初期化、最初のフレーム。
• permission-audit — 使用頻度の低いサードパーティ製アプリが保持する危険な権限を検出します。

MCP リソース

URI ベースの読み取り専用エンティティ：

• android://devices — 接続中のデバイス
• android://device/{serial} — デバイスの詳細（モデル／ブランド／バージョン／ディスプレイ）
• android://app/{packageName}/activities — パッケージが公開するアクティビティ（exported／launchable フラグ）
• android://device/{serial}/processes — 実行中のプロセス

ツール（76）

9 カテゴリです。実行時にツールを検索するには search-tools を使用してください。全リストは下に折りたたまれています。

カテゴリ	ツール数
システム（バッテリー／ネットワーク／設定／ディスプレイ／向き／ポート転送／Wi-Fi／モバイルデータ）	19
アプリ（インストール／起動／権限／インテント／データ消去）	14
UI（タップ／スワイプ／スクリーンショット／階層／アクセシビリティ／インデックス指定の注釈付きタップ／画面録画）	14
エミュレーター（AVD の起動／停止、スナップショット管理）	7
デバイス（一覧／情報／プロパティ／ワイヤレス接続）	5
デバッグ（バグレポート／メモリ／グラフィックス／CPU／診断）	5
Logcat（取得／フィルター／消去／クラッシュ抽出）	4
ファイル（一覧／取得／プッシュ／削除）	4
シェル（ゲート制御された execute-shell）	1
集約（device-health、analyze-app）	2
メタ（search-tools）	1

ツールの全リスト

デバイス（5）

list-devices、get-device-info、get-device-properties、connect-device、disconnect-device

アプリ（14）

list-packages、get-package-info、install-app、uninstall-app、launch-app、stop-app、clear-app-data、grant-permission、revoke-permission、open-url、send-broadcast、get-current-activity、is-app-installed、get-app-intents

UI 自動化（14）

take-screenshot、dump-ui-hierarchy、ui-snapshot-a11y、tap、long-press、swipe、input-text、press-key、drag-and-drop、start-screen-recording、pull-screen-recording、double-tap、take-annotated-screenshot、tap-element

Logcat（4）

get-logcat、clear-logcat、search-logcat、get-crash-logs

エミュレーター（7）

list-avds、start-emulator、stop-emulator、list-snapshots、load-snapshot、save-snapshot、delete-snapshot

ファイル（4）

list-files、pull-file、push-file、delete-file

システム（19）

get-battery-info、get-network-info、change-setting、get-setting、set-display-size、set-display-density、keep-screen-on、port-forward、reverse-forward、list-forwards、remove-forward、toggle-wifi、toggle-mobile-data、open-notification、lock-device、unlock-device、get-orientation、set-orientation、list-settings

デバッグ（5）

bugreport、get-mem-info、get-gfx-info、get-cpu-info、doctor

シェル（1）

execute-shell — ANDROID_MCP_ALLOW_SHELL によるゲート制御

集約

device-health — バッテリー、メモリ、CPU、ネットワークを 1 回の呼び出しで取得します（約 7 KB の応答。注意事項付きの 4 つのサブシステム）。 analyze-app — パッケージ情報、メモリ、アクティビティを集約します。

メタ

search-tools — キーワードで他のツールを検索します。常に有効です。

アーキテクチャ

Claude → MCP stdio → src/index.ts
                      ├── adb.ts (execFile wrapper)
                      ├── tools/utils.ts (wrapToolHandler, shellEscape, validation)
                      └── tools/{device,apps,ui,logcat,emulator,files,system,debug,shell,aggregations}.ts
                                  ↓
                          ADB CLI (USB / TCP-IP / Emulator)
                                  ↓
                          Android Device

@us-all/mcp-toolkit を基盤としています：

• extractFields — トークン効率に優れた応答の射影（ADB のフラット配列エンドポイントではスキップ）
• aggregate(fetchers, caveats) — device-health／analyze-app 用のファンアウトヘルパー
• createWrapToolHandler — WriteBlockedError／ShellBlockedError のパススルーと、構造化された ADB エラー（{code, stderr}）
• wrapImageToolHandler（Android 専用）— base64 PNG のサニタイズ
• search-tools メタツール

セキュリティ

• デフォルトでは読み取り専用です。 ANDROID_MCP_ALLOW_WRITE=true が設定されていない場合、書き込みはブロックされます。
• シェルの制御は別です。 書き込みが有効でも、ANDROID_MCP_ALLOW_SHELL=true が設定されていない場合、execute-shell はブロックされます。信頼レベルは別々です。
• シェルインジェクション対策済みです。 シングルクォート方式のエスケープには shellEscape を使用します。設定キー、パッケージ名、権限、コンポーネント、ブロードキャストアクション／エクストラは、zod の正規表現ホワイトリストで入力を検証します。
• パストラバーサルをブロックします。 デバイスパスには、絶対パスであること、.. を含まないこと、シェルのメタ文字を含まないことが求められます。
• エラーをサニタイズします。 すべてのエラー出力で、API キー、トークン、パスワードを伏せ字にします。

技術スタック

Node.js 22+ • TypeScript strict ESM • pnpm 10 • @modelcontextprotocol/sdk 1.29+ • zod v4 • fast-xml-parser • vitest（フォークプール分離）。

ライセンス

MIT