admcp - Android Debug MCP

admcp

admcp は、Android 開発向けのローカルファーストな Model Context Protocol（MCP）サーバーです。 任意の MCP stdio クライアントを実機またはエミュレーターに接続し、UI の検査、スクリーンショット、logcat、Java/Kotlin JDI デバッグ、ネイティブ LLDB、Flutter/Dart DAP、Compose の検査、Perfetto トレース、ヒープダンプ、アーティファクト、証拠に基づく診断に対応する、型付けされた 51 個のツールを提供します。

root 権限は不要です。クラウドアカウントも必要ありません。

クイックスタート | できること | プロンプト例 | admcp を選ぶ理由 | ドキュメント

状況：v1、51 個のツール。OnePlus CPH2747（API 36、arm64-v8a）で実機テスト済みです。 詳細な証拠と残る制限については、 実装状況をご覧ください。

クイックスタート

1. JDK 21 と Android SDK platform-tools（adb）をインストールします。
2. GitHub Releasesからadmcp-<version>.zipをダウンロードして 展開します。同じリリースにあるadmcp-<version>.mcpbは、MCPB 対応クライアントから インストールできます。
3. MCP クライアントに、Windows ではbin/admcp.bat、Linux と macOS では bin/admcpを指定します。

任意の MCP stdio クライアントで利用できます。以下の JSON では一般的なmcpServers 形式を使用しています。コマンドと引数は、使用するクライアント（Claude Code、Cursor、 VS Code、Codex、Gemini CLI など）に合わせて調整してください。

{
  "mcpServers": {
    "admcp": {
      "command": "C:\\Tools\\admcp\\admcp-<version>\\bin\\admcp.bat",
      "args": [
        "--platform-tools", "C:\\Android\\Sdk\\platform-tools",
        "--artifacts", "C:\\temp\\admcp-artifacts"
      ]
    }
  }
}

Linux と macOS では、commandに/opt/admcp/admcp-<version>/bin/admcpを指定します。

インストールを確認します。

C:\Tools\admcp\admcp-<version>\bin\admcp.bat --selftest

Linux と macOS の場合：

/opt/admcp/admcp-<version>/bin/admcp --selftest

stderr にcatalog=51 registered=51 version=<version>と表示されます。 その後、サーバーは stdio 経由で MCP を通信します。stdout はプロトコル通信専用です。

できること

51 個すべてのツールの仕様は docs/architecture/mcp-tool-catalog-v1.mdにあります。 カタログはコントラクトテストで検証されています。

プロンプト例

admcp を接続したら、エージェントに次のようなことを尋ねてみてください。

Inspect the current screen, find the INCREMENT button, tap it, and verify the counter changed.
Start logcat, reproduce the crash, then summarize the stack trace and the last 50 lines before it.
Launch the app, attach JDI, set a breakpoint in MainActivity, and show locals when it hits.
Inspect this Compose screen and tell me which accessibility node is the DELETE COUNTER button.
Record a 5-second Perfetto trace and summarize what happened.
Attach LLDB to the native library, break in fixture_increment, and show the registers.

admcp を選ぶ理由

多くの Android MCP ツールは、コマンドの薄いラッパーにすぎません。admcp はデバイス、ワークスペース、プロセス、セッションの状態をまとめて管理し、型付きスキーマ、成果物、安全性チェックを備えたデバッグ用プリミティブを公開します。

対象となるのは、次の方々です。

• Claude Code、Cursor、その他のエージェントを使って、実機を調査・デバッグしたい Android 開発者。
• adb の文字列を解析する代わりに、安定した型付き Android アクションを必要とするエージェントの構築者。
• デバイスから再現可能な証拠を必要とする QA や自動化のワークフロー。

IDE の前に座る人間にとっては、Android Studio のほうが適したツールです。admcp は、人間がすべてのクリックを操作しなくても、調査、操作、デバッグを行う必要があるエージェント向けです。

仕組み

flowchart LR
    Client["MCP client / agent"] -->|stdio| Server["admcp (MCP server)"]
    Server --> ADB["ADB / Android CLI"]
    Server --> JDI["JDI (JDWP client)"]
    Server --> LLDB["lldb-dap"]
    Server --> DAP["Flutter DAP"]
    ADB --> Device["Android device / emulator"]
    JDI -.->|via adb forward| ADB
    LLDB -.->|via adb forward / lldb-server| ADB
    DAP -.->|via adb forward| ADB

サーバーは Android ツールチェーンと並んで、マシン上で動作します。プロジェクトやデバイスのデータを外部にアップロードすることはありません。

検証済み

• 検証済みホストで、186 件のテストを実施し、失敗は 0 件でした。
• カタログは MCP stdio 経由で 51 個すべてのツールを登録します。
• 実機：OnePlus CPH2747、API 36、arm64-v8a。
• JDI：アタッチ、ブレークポイント、ステップ実行、スタック、ローカル変数、読み取り専用評価。
• LLDB：アタッチ、ブレークポイント、スタック、レジスター、範囲を制限したメモリ読み取り、モジュール。
• Flutter：DART_DAP のブレークポイント、スタック、変数、ステップ実行、一時停止、デタッチ。
• Compose：アクセシビリティツリーの調査と、検証済み UI アクション。
• パフォーマンス：Perfetto のキャプチャ／分析と HPROF ヒープダンプのキャプチャ。
• 証拠：logcat、クラッシュバッファー、成果物、セッションタイムライン、診断情報。

デバイスに依存する統合テストは、デバイスが接続されていない場合はスキップされます。受け入れ証拠の詳細は、実装状況を参照してください。

要件

• JDK 21。
• Android SDK platform-tools（adb）。
• Windows、Linux、または macOS。
• 任意：Android CLI、Flutter SDK、NDK の lldb／lldb-server、lldb-dap、および接続済みのデバイスまたはエミュレーター。

サポート対象はデバッグ可能な開発者向けビルドのみです。root 化や Android のセキュリティ回避は対象外です。

ソースからビルド

gradlew.bat clean test
gradlew.bat :app:admcp:installDist

./gradlew clean test
./gradlew :app:admcp:installDist

設定

workspace_trust が成功するのは、サーバー起動時に --trust-workspace で渡された正規のルートに限られます。ツールの引数で承認を自己申告することはできません。

既知の制限事項

• 検証済みのデバイスは API 36 の OnePlus CPH2747 です。他の OEM、API、トランスポートの組み合わせは保証対象外です。
• 検証済みのデバイスでは、JDI と LLDB による同時検査は安定していません。debug_attach(switchBackend=true) を使えば、順次切り替えて使用できます。
• Compose の TREE はアクセシビリティ階層を使用します。内部セマンティクス、スロットテーブル、再コンポジションのデータを取得するには、アプリへのインストルメンテーションが必要です。
• ホストの trace_processor_shell は同梱されていないため、Perfetto SQL ツールがインストールされていない場合、トレース分析は範囲を限定した概要を返します。
• Crashlytics のイシュークラスターを取得するには android auth login が必要です。ローカルのクラッシュバッファーが引き続きデフォルトの証拠ソースです。
• ネイティブ LLDB を使用するには、別途インストールした lldb-dap と、ABI が一致する lldb-server が必要です。
• ホストの確認ダイアログを表示するには、対話型デスクトップが必要です。ヘッドレスサーバーではフェイルクローズし、ワンショットトークンに切り替わります。

詳細と正確なエラー動作については、実装状況を参照してください。

セキュリティ

• サポート対象は、デバッグ可能な開発ビルドのみです。
• プロジェクトが制御するコードは、ワークスペースの信頼が明示的に許可された後にのみ実行されます。
• 破壊的な UI 操作には、ホストの確認、またはセッションと操作にひも付けられたワンショットトークンが必要です。
• アーティファクトの読み取りはストアルート内に限定され、デフォルトでサイズが制限され、機密情報が除去されます。
• このサーバーはローカル優先です。クラウドアカウントは必要ありません。

ドキュメント

• 技術設計
• 実装状況
• ツールカタログ（Markdown）
• ツールカタログ（JSON）
• MCP Registry への公開

コントリビューション

イシューやプルリクエストを歓迎します。公開ツールカタログはバージョン管理されています。公開ツールの追加や名称変更を行う前に、イシューを作成してください。PR を送る前に gradlew test を実行してください。

admcp がエージェントの作業時間を節約できた場合は、スターを付けていただくと、より多くの Android 開発者に見つけてもらいやすくなります。

ライセンス

Apache License 2.0。詳細はLICENSEを参照してください。