Expo Android MCP

expo-android

ADB 経由で Android エミュレーターを自動操作する MCP サーバーです。

要件

• Node 18+
• Android SDK platform-tools（adb）が使用可能であること
• Android エミュレーターまたはデバイスが接続されていること

adb を確認します：

adb devices

インストール

Claude Desktop、ワンクリック： 最新リリースから expo-android.mcpb をダウンロードし、Settings → Extensions にドラッグします。両方のフィールドは空のままでかまいません。adb は自動検出され、接続されているデバイスが1台だけの場合は、そのデバイスがデフォルトで使用されます。

npm 経由：

npm install -g @fndchagas/expo-android
# or
npx -y @fndchagas/expo-android

クイックスタート

1. エミュレーターを起動するか、デバイスを接続します。
2. doctor を実行して、adb とデバイスの選択を検証します。
3. inspect、tapElement、inputText などを使用します。

例：

await client.callTool({ name: 'expo-android.doctor', arguments: {} });
await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, maxElements: 200 },
});

Claude Code CLI で使用する

claude mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

OpenAI Codex CLI で使用する

codex mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

または、~/.codex/config.toml を編集します：

[mcp_servers.expo-android]
command = "npx"
args = ["-y", "@fndchagas/expo-android"]
env = { ADB_PATH = "/Users/you/Library/Android/sdk/platform-tools/adb", ADB_SERIAL = "emulator-5554" }

シリアル番号の選択優先順位： serial パラメーター（ツール呼び出しごと）→ setDevice による上書き → ADB_SERIAL 環境変数 → 自動（デバイスが1台だけの場合）。

環境変数

変数	デフォルト	説明
ADB_PATH	adb	adb 実行ファイルのパス
ADB_SERIAL	任意	対象デバイスのシリアル番号（クリアして自動検出する場合は auto）
ADB_TIMEOUT_MS	15000	adb コマンドのタイムアウト
ADB_MAX_BUFFER_MB	10	出力バッファーの最大サイズ
ADB_DEBUG	0	adb の診断情報を stderr に記録
MCP_TRANSPORT	stdio	トランスポート：stdio、http、または both
PORT	7332	http/both 使用時の HTTP ポート

トラブルシューティング

adb が見つからない（spawn adb ENOENT）

adb が見つからない場合でもサーバーは起動します。adb が使用可能になるまで、ツールは ADB executable not found エラーを返します（診断には doctor を実行してください）。解決するには、ADB_PATH を設定するか、SDK のパスをエクスポートします：

export ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb"
# or
export ANDROID_HOME="$HOME/Library/Android/sdk"

複数のデバイスが接続されている場合は、対象デバイスを ADB_SERIAL に設定します。 実行中に setDevice を実行することもできます：

await client.callTool({
  name: 'expo-android.setDevice',
  arguments: { serial: 'emulator-5554' },
});

PATH または SDK の環境変数を更新した場合は、新しい環境を読み込めるように MCP プロセスを再起動してください。

テスト

npm run build
npm test

ツール

ツール名は単純な識別子（例：tap）です。MCP クライアントは、登録したサーバー名をプレフィックスとして付加します。

• devices — 接続されているデバイスとエミュレーターを一覧表示します。
• doctor — adb が利用可能かを検証し、接続されているデバイスを表示します。
• setDevice — この MCP プロセスで使用するアクティブなデバイスのシリアル番号を上書きします。
• inspect — UI ダンプを要約付きで解析し、要素を表示します（スクリーンショットは任意です）。
• screenshot — スクリーンショットのみをキャプチャします（base64 またはファイルパス）。
• findElement — 検索条件に一致する要素を返します。
• tapElement — 要素を検索し、その中央をタップします。
• waitForElement — 要素が表示されるまで待機します（状態チェックは任意です）。
• assertElement — 要素の存在と状態を確認します。
• tap — x/y 座標をタップします。
• swipe — 座標間をスワイプします。
• longPress — 座標を長押しします。
• inputText — フォーカスされているフィールドにテキストを入力します。
• keyEvent — Android のキーイベントを送信します（例：BACK、HOME）。
• openApp — パッケージ名を指定してアプリを起動します。
• listPackages — インストール済みのパッケージ名を一覧表示します。
• installExpoGo — 固定された Expo Go APK をダウンロードし、adb install -r でインストールします（url の上書きで指定できるのは、公式の github.com/expo/expo-go-releases URL のみです）。

すべてのツールは MCP アノテーション（readOnlyHint／destructiveHint）を宣言しているため、クライアントは検査ツールを自動承認し、デバイスを操作するツールには承認を求めることができます。

検索条件

次のツールは柔軟な検索入力を受け付けます：findElement、tapElement、 waitForElement、assertElement。

共通フィールド：

• text、textContains
• contentDesc、contentDescContains
• resourceId、resourceIdContains
• class
• normalizeWhitespace、caseInsensitive

MCP の使用例

検査

const result = await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, includeScreenshot: false, maxElements: 200 },
});

検査オプション：

• includeScreenshot（デフォルト：false）
• screenshotMode：base64 または path
• screenshotPath：path 使用時の任意のファイルパス
• maxElements：返す要素数の上限
• includeElements：要素を返すか、要約のみを返すか

Doctor

await client.callTool({
  name: 'expo-android.doctor',
  arguments: {},
});

呼び出しごとにシリアル番号を上書き

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Search', serial: 'emulator-5554' },
});

要素をタップ

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Private account' },
});

待機＋確認

await client.callTool({
  name: 'expo-android.waitForElement',
  arguments: { text: 'Save', timeout: 10000, shouldBeClickable: true },
});

await client.callTool({
  name: 'expo-android.assertElement',
  arguments: { text: 'Private account', shouldBeChecked: true },
});