Replicant MCPをClaude Codeにつないでビルドと画面操作を任せる

Replicant MCPは、Androidアプリのビルド、エミュレーター操作、画面のタップ、ログの確認を、Claude Codeから会話で頼めるようにするMCPサーバーです。「チェックアウトの流れを直したので、ビルドして最後の確認画面まで進めて」と頼むと、Claudeが一連の操作を順に実行します。

この記事では、Claude Codeへの追加から、動作確認、権限の絞り方、うまく動かないときの切り分けまでを扱います。MCPの追加方法そのものはClaude CodeのMCPサーバー設定ガイドが詳しいので、ここではReplicant固有の部分に絞ります。

Replicant MCPでできること

READMEによると、Replicant MCPは次の領域をツールとして公開します。Claudeのコネクタ一覧では「Anthropic verified」の表示があり、ツールは14個、6カテゴリです。

ツール名は adb-device、adb-app、adb-logcat、adb-shell、emulator-device、gradle-build、gradle-test、gradle-list、gradle-get-details、ui-query、ui-action、ui-capture、cache、rtfm です。rtfm は、「build」「adb」「emulator」「ui」などのカテゴリ名を渡すと各ツールの説明を返す窓口です。

仕組みの要点: トークンを食わない2つの設計

Androidのビルド出力は数千行になることがあります。そのままコンテキストに流すと、肝心の失敗箇所が埋もれます。Replicantは2つの方法でこれを避けます。

Gradleの出力は要約とIDで返す

gradle-build の戻り値は、成否、所要時間、APKサイズ、警告数の要約と、ビルドIDです。失敗の中身が必要なときだけ、Claudeが gradle-get-details にIDを渡して、logs、errors、tasks のいずれかを取り出します。READMEは、生のGradle出力が約5,000トークンのところ、要約は約50トークンと説明しています。設計文書の「90〜99%削減」という数字は、同ツールの自己申告です。自分のプロジェクトで効果を見積もるなら、ビルド前後でコンテキストの消費量を比べるのが確実です。

画面はアクセシビリティツリーで読む

スクリーンショットを画像認識にかけて座標を推測する代わりに、ui-query が画面の要素をテキストとIDで返します。要素は text(完全一致)、textContains(部分一致)、resourceId、className で探せます。「編集」を含むボタンのうち「John」に最も近いものを探す、という空間検索もできます。

見つからなかったときは、段階的に別の手段へ落ちます。

maxTier に 3 を指定すると、画像を返す段階(4と5)に進みません。日常の検索はテキストだけで済ませたいときの指定です。

前提を整える

READMEが挙げる前提は、Node.js 18以上、adb と emulator がPATHにあるAndroid SDK、ビルドを任せるなら gradlew があるAndroidプロジェクトです。次のコマンドで確認できます。

node --version
adb --version
emulator -version

SDKをまだ入れていないmacOSでは、READMEがHomebrewを使う手順を載せています。順番に意味があるので、並べ替えないでください。

brew install --cask temurin@17
brew install --cask android-commandlinetools
export ANDROID_HOME="$HOME/Library/Android/sdk"
mkdir -p "$ANDROID_HOME"
yes | sdkmanager --licenses
sdkmanager --install "platform-tools" "emulator" \
  "system-images;android-34;google_apis;arm64-v8a"

ANDROID_HOME を先に作るのは、sdkmanagerのインストール先がないと失敗するためです。ライセンスの承諾を先に済ませるのは、未承諾のパッケージがあるとインストールが途中で止まるためです。システムイメージのアーキテクチャーは、Apple Siliconなら arm64-v8a、Intel Macなら x86_64 です。

実機だけを使うなら、brew install --cask android-platform-tools でadbだけ入れれば足ります。

Apple Siliconでの注意

サポート表では、CIで検証しているエミュレーターはGoogle APIsのx86_64です。Apple Siliconは「Rosettaを介した動作で、機能するがCIでは検証していない」という扱いです。一方、READMEの導入手順はarm64-v8aのイメージを例に挙げています。両者は食い違って見えるので、M系Macで起動に失敗したときは、イメージのアーキテクチャーを変えて試す余地があります。

Claude Codeに追加する

追加は1行です。

claude mcp add replicant -- npx -y replicant-mcp

-- の前がClaude Codeのオプション、後ろがサーバーを起動するコマンドです。スコープを指定しない場合、サーバーは追加したプロジェクトにだけ、自分専用で登録されます。チームで共有するなら --scope project を付けて .mcp.json に書き出します。

接続は claude mcp list または会話中の /mcp で確かめます。

claude mcp list
claude mcp get replicant

環境が整っているかは、別にグローバルインストールして replicant doctor を実行すると診断できます。

npm install -g replicant-mcp
replicant doctor

Gradleがプロジェクトを見つけられないとき

MCPサーバーは、Androidプロジェクトのディレクトリとは別の場所から起動されることがあります。そのままだと gradlew が見つからず、ビルドが失敗します。プロジェクトの場所は環境変数で伝えます。

claude mcp add replicant \
  --env REPLICANT_PROJECT_ROOT=/path/to/my-android-app \
  -- npx -y replicant-mcp

設定ファイルを使う場合は、REPLICANT_CONFIG にYAMLのパスを渡し、build.projectRoot を書きます。環境変数と設定ファイルの両方があるときは、環境変数が優先されます。どちらも未設定なら、カレントディレクトリが使われます。

主な設定キーは次のとおりです。

ログは REPLICANT_LOG_LEVEL(error、warn、info、debug)と REPLICANT_LOG_FORMAT(jsonで構造化)で調整でき、標準エラー出力に書かれます。

動作確認の頼み方

最初は破壊的でない操作から始めると、環境の問題を切り分けやすくなります。

1. 「接続中のデバイスとエミュレーターを一覧にして」と頼み、adb-device が動くか見る
2. 「このプロジェクトのモジュールとバリアントを教えて」と頼み、gradle-list が gradlew を見つけるか確かめる
3. 「デバッグAPKをビルドして、結果の要約だけ教えて」と頼む
4. 「エミュレーターに入れて起動し、ログインボタンを探して」と頼む

READMEの例では、次のような依頼文が示されています。

「チェックアウトの流れを変えたので、アプリをビルドして、テスト商品でチェックアウトを通し、確認画面が出ることを確かめて」

この依頼では、ビルド、インストール、起動、カテゴリーや商品のタップ、フォーム入力、注文確定までがひとつの流れになります。READMEの出力例は説明用であり、自分の環境で同じ結果が出る保証ではありません。

権限を絞る

adb-shell は端末のシェルコマンドを実行します。Replicantには安全装置があり、reboot、shutdown、halt、poweroff や、su、sudo、dd、mkfs、wipe などの破壊的・権限昇格のコマンドを拒否します。;、&、|、バッククォート、括弧によるコマンドの連結や、$VAR の展開も拒否されます。

ただし、ドキュメント自身が、拒否リストは「ベストエフォートの安全網であり、サンドボックスではない」と書いています。たとえば cat /sdcard/... のような読み取りは、adbのユーザーに権限があれば通ります。

Claude Code側でも絞れます。MCPツールは mcp__<サーバー名>__<ツール名> の形で指定できるので、サーバー名を replicant で登録した場合、.claude/settings.json に次のように書けます。ビルドと読み取りは通し、シェルだけ毎回確認にする例です。

{
  "permissions": {
    "allow": [
      "mcp__replicant__gradle-build",
      "mcp__replicant__gradle-get-details",
      "mcp__replicant__ui-query"
    ],
    "ask": ["mcp__replicant__adb-shell"]
  }
}

許可ルールの書き方はClaude Codeのパーミッション設定にまとめています。CLAUDE.mdに「破壊的な操作の前に確認する」「テストはエミュレーターでのみ実行する」と書いておく方法もあります。

つまずきやすい点

次の症状は、どれも設定か環境の見直しで解消します。

このほか、操作できる端末は同時に1台です。複数台を並列に動かすことはできません。Gradleラッパーのないプロジェクトも対象外です。Windowsはベストエフォートで、エミュレーターを使う統合テストはLinuxだけで実行されています。

スクリーンショットの扱い

スクリーンショットは作業ディレクトリの .replicant/screenshots/ に保存されます。画面に映った個人情報や認証情報もそのまま残ります。.gitignore に .replicant/ を追加し、不要になったら rm -rf .replicant/ で消します。

使いどころの見極め

向いているのは、ビルドして動かして画面で確かめる往復を何度も繰り返す作業です。ビルド失敗の原因探しは、要約とID方式のおかげでコンテキストを節約できます。

向かないのは、アクセシビリティ情報が乏しいアプリの細かい操作と、5分を超える大規模ビルドです。前者は視覚モードに落ちるため、画像分のトークンがかかります。後者は既定の設定では途中で打ち切られるおそれがあります。

CI/CDの側からモバイルビルドを扱うなら、Bitrise MCPでビルド起動と失敗調査を任せる手順も参考になります。ローカルの端末操作はReplicant、クラウドのパイプラインはBitriseという分担になります。