androidbuild-mcp

AndroidBuildMCP

AI エージェントに Android を直接操作させましょう。AndroidBuildMCP は、あらゆる MCP クライアント（Claude Code、Cursor、...）から、実際の Android アプリのビルド、デプロイ、操作、デバッグを可能にする MCP サーバーです。読みやすいエラーを出力する Gradle ビルド、エミュレーター管理、adb によるデプロイ、logcat のキャプチャ、UI の完全な自動化に対応しています。

クイックスタート

必要なもの：Node 18 以降、Android SDK（ANDROID_HOME またはデフォルトのインストール先）、Gradle ビルド用の JDK 17 以降。

インストール手順は不要です。初回実行時に npx がサーバーを取得します。

Claude Code

claude mcp add androidbuild -- npx -y @asjackson/androidbuild-mcp

その他の MCP クライアント

{
  "mcpServers": {
    "androidbuild": {
      "command": "npx",
      "args": ["-y", "@asjackson/androidbuild-mcp"]
    }
  }
}

git clone https://github.com/dev-jackson/androidbuild-mcp.git
cd androidbuild-mcp
npm install && npm run build
claude mcp add androidbuild -- node /absolute/path/to/androidbuild-mcp/dist/index.js

次に、エージェントに doctor を実行するよう依頼してください。SDK、adb、エミュレーター、Java、接続済みデバイスを確認し、不足しているものを正確に知らせます。

エージェントにできること

• ビルドとテスト — build_app はコンパイルし、何千行もの Gradle のログの代わりに、簡潔な file:line 形式のコンパイラーエラーを返します。test_app / test_instrumented は解析済みの成功／失敗の概要を返します。Lint、クリーン、カバレッジ（Kover/Jacoco）にも対応しています。
• エミュレーターの管理 — AVD の一覧表示、作成、起動（完全な起動を待ってシリアルを返します）、データ消去、終了ができます。スクリーンショット用に、GPS の位置、ダークモード、見栄えのよいデモ用ステータスバーを設定できます。
• デプロイ — build_run は 1 回の呼び出しでコンパイル、インストール、起動を行います。adb によるインストール／アンインストール／データ消去／アプリ情報の取得に対応し、接続デバイスが 1 台だけの場合は適切なデバイスを自動選択します。
• 画面の確認 — snapshot_ui は、タップ座標付きの名前付き要素を簡潔なリストとして返します（Compose のセマンティクスを統合し、ノイズを除去します）。screenshot は画像を返します。annotate: true を指定すると、ビジョン機能を使って番号付きの枠を描画し、画像内のテキストや WebView の内容も検出します。
• 画面の操作 — タップ、スクロール、スワイプ、ドラッグ、長押し、入力（キーボードに対応し、クリア／送信も可能）、ハードウェアキー操作ができます。また、要素が表示されるまでポーリングする wait_for_ui にも対応しています。
• ログの確認 — アプリでフィルタリングしたバックグラウンドの logcat キャプチャ、一度限りのダンプ、スタックトレース用のクラッシュバッファに対応しています。
• 新しいアプリの開始 — scaffold_android_project は、そのままビルドできる最小限の Compose プロジェクトを生成します。

セッションのデフォルト値（session_set_defaults）を使うと、プロジェクト、モジュール、バリアント、デバイスを一度設定するだけで、以降の呼び出しでは引数を指定せずに使えます。

ツールリファレンス

stdio 経由で 53 個のツールを利用できます。各ツールはプレーンな引数を受け取り、テキスト（screenshot の場合は画像）を返します。

環境とプロジェクト

セッションのデフォルト値

ビルド、テスト、品質

デバイスとエミュレーター

アプリのライフサイクル

UI 自動化

ログと録画

スキャフォールディング

正確なタップ

adb 側の座標はすべて同じ座標空間（デバイスのピクセル）を使用しますが、MCP クライアントではスクリーンショットが拡大・縮小表示されることがよくあります。画像を見てピクセル位置を目測すると、タップ位置がずれてしまいます。対象を正確にタップする安全な方法は 3 つあります。

1. snapshot_ui — 名前付きの各要素について、デバイスピクセル上の正確な中心座標を返します。推奨される方法です。
2. screenshot { annotate: true } + tap_element { element: N } — 画像上に描かれた番号でタップします。対応付けは元の PNG 上で解決されるため、クライアント側の拡大・縮小でずれることはありません。
3. tap { xPct, yPct } — 画面に対する割合（0〜1）を指定します。long_press／swipe／drag でも使用できます。解像度に依存しません。

実際のピクセル座標が分かっている場合は、tap { x, y } も引き続き使用できます。

信頼性

リリース前に、実際のエミュレーターと実際のプロジェクトで、通常のケースから境界ケースまで各ツールをテストしました。シナリオごとの検証結果はqa-results.mdにあります。エージェントのワークフローで誤作動を防ぐための詳細をいくつか紹介します。

• type_text は文字を入力する前にソフトキーボードの表示を待機します（そうしないと、フィールドにフォーカスした直後に入力した場合、最初の数文字が通知されずに失われます）。
• scroll は画面サイズに基づいて、長くゆっくりとしたスワイプを行います。短く速いスワイプは、一部のリストで無視されることがあります。ランチャーで必要となる long_press の長押し時間は 1000 ミリ秒です。
• 画面外へのタップは無視されず、実際の画面サイズを示すエラーとして返されます。
• テキスト量の多い画面（電子書籍の WebView など）は、コンテキストがあふれないように出力を制限しています。代わりに snapshot_ui { filter } で検索できます。
• ビルド／テスト／デバイスのエラーは、次に呼び出すツールを示す、短く実行可能なメッセージとして返されます。

オプション

• Google の Android CLIを使うと、screenshot { annotate: true } が利用できます。doctor を実行すると、お使いの OS 用のインストーラーコマンドが 1 行で表示されます。
• ADBKeyboard IMEを使うと、ASCII 以外の文字を type_text で入力できます（adb 単体では ASCII のみ対応します）。APK を一度インストールすれば、サーバーが自動的に使用します。

開発

npm install
npm test            # unit tests (no real processes spawned)
npm run dev         # run the server from source
npm run build       # compile to dist/

ライセンス

MIT — LICENSEを参照してください。

概念面ではXcodeBuildMCPに着想を得ていますが、Android ツールチェーンを中心に独自に実装しています。