Metro MCP

metro-mcp

React Native のランタイムのデバッグ、検査、自動化に対応する、プラグインベースの MCP サーバーです。Chrome DevTools Protocol を介して Metro バンドラーに接続します。ほとんどの機能で、アプリのコード変更は不要です。

Expo、bare React Native、および Metro + Hermes を使用するあらゆるプロジェクトで動作します。

---

目次

• クイックスタート
• 要件
• 仕組み
• 機能
• Chrome DevTools
• Claude Code のステータスバー
• テストの記録
• アプリの統合
• 設定
• カスタムプラグイン
• 互換性

---

クイックスタート

Claude Code

claude mcp add metro-mcp -- npx -y metro-mcp
# or with Bun
claude mcp add metro-mcp -- bunx metro-mcp

Codex

codex mcp add metro-mcp -- npx -y metro-mcp
# or with Bun
codex mcp add metro-mcp -- bunx metro-mcp

Codex はデフォルトで MCP サーバーを ~/.codex/config.toml に保存します。Codex CLI と IDE 拡張機能は、この設定を共有します。

手動で設定する場合は、次のようにします。

[mcp_servers.metro-mcp]
command = "npx"
args = ["-y", "metro-mcp"]

OpenCode

OpenCode の対話型 MCP インストーラーを実行します。

opencode mcp add

ローカルサーバーを選択し、名前を metro-mcp にして、コマンドに npx -y metro-mcp を指定します。

手動で設定する場合は、プロジェクトの opencode.json に追加するか、グローバルにインストールするには ~/.config/opencode/opencode.json に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "metro-mcp": {
      "type": "local",
      "command": ["npx", "-y", "metro-mcp"],
      "enabled": true
    }
  }
}

または Bun を使用します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "metro-mcp": {
      "type": "local",
      "command": ["bunx", "metro-mcp"],
      "enabled": true
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "metro-mcp": {
      "command": "npx",
      "args": ["-y", "metro-mcp"]
    }
  }
}

または Bun を使用します。

{
  "mcpServers": {
    "metro-mcp": {
      "command": "bunx",
      "args": ["metro-mcp"]
    }
  }
}

複数のエージェントにインストールする

複数の MCP クライアントを使用している場合、add-mcp を使って、Claude Code、Codex、Cursor、OpenCode、VS Code など、対応するエージェントの設定を書き込めます。

npx add-mcp metro-mcp --all -g -y

metro-mcp は複数のエージェントを同時にサポートします。標準の stdio インストールでは、同じプロジェクトディレクトリと Metro／設定オプションに対して、ローカルの共有デーモンを起動するか、既存のものを再利用します。そのため、Codex、Claude Code、Cursor などのクライアントが、実行中の同じ Metro アプリに同時に接続し、同じログ、ネットワークリクエスト、エラー、ランタイムの状態を確認できます。

共有 HTTP サーバー／Supergateway

長時間稼働する MCP エンドポイントを自分で 1 つ公開する場合は、共有サーバーを明示的に起動します。

npx -y metro-mcp serve --mcp-port 8765

これは http://127.0.0.1:8765/mcp で Streamable HTTP を提供します。このエンドポイントは、2025 年の MCP ハンドシェイクと 2026-07-28 のネゴシエーションの両方に対応しています。/sse と /messages は意図的に使用できません。supergateway などのツールを使うと、リクエストごとに新しい stdio プロセスを起動する代わりに、Streamable HTTP エンドポイントを指定できます。

カスタム Metro ポートを使用する

codex mcp add metro-mcp -- npx -y metro-mcp --port 19000
# or
claude mcp add metro-mcp -- npx -y metro-mcp --port 19000

OpenCode の場合は、コマンド配列にポートを追加します。

"command": ["npx", "-y", "metro-mcp", "--port", "19000"]

---

要件

• Node.js 18+ または Bun 1.0+
• iOS：Simulator を含む Xcode 14+（ほとんどの操作で xcrun simctl を使用します）
• Android：adb が PATH に含まれている Android SDK
• IDB (任意)：一部の iOS 操作は IDB (idb-companion) にフォールバックします。brew install idb-companion でインストールしてください。IDB が必要な場合は、ツールが通知します。

---

仕組み

metro-mcp は Chrome DevTools と同じ方法で、実行中の Metro 開発サーバーに接続します。

1. ポートをスキャンして Metro を検出します（8081、8082、19000–19002）
2. Chrome DevTools Protocol（CDP）を介して Hermes に接続します
3. コンソールログ、ネットワークリクエスト、エラーをバッファーにストリーミングします
4. すべてを MCP のツール、リソース、プロンプトとして公開します

コアのデバッグ機能では、アプリの変更は不要です。

---

機能

プラグイン	ツール	説明
console	2	フィルタリング機能付きのコンソールログ収集
network	6	ネットワークリクエストの追跡、レスポンス本文の確認、統計情報
errors	3	実行時例外の収集と Metro バンドルエラーの検出
evaluate	1	アプリのランタイムで JavaScript を実行
device	4	デバイス管理、接続状態、アプリの再読み込み
environment	4	ビルドフラグ、プラットフォーム定数、環境変数、Expo 設定の確認
source	1	スタックトレースのシンボリケーション
redux	3	Redux の状態確認とアクションのディスパッチ
components	5	React コンポーネントツリーの確認
storage	3	AsyncStorage の読み取り
simulator	6	iOS シミュレーター／Android デバイスの制御
deeplink	2	クロスプラットフォームのディープリンクテスト
permissions	5	iOS シミュレーターと Android エミュレーターでのアプリ権限の確認と管理
ui-interact	6	UI オートメーション（タップ、スワイプ、入力）
navigation	4	React Navigation／Expo Router の状態
accessibility	3	アクセシビリティ監査
commands	2	カスタムアプリコマンド
automation	3	非同期状態の変化を待機／ポーリングするヘルパー
profiler	9	CPU プロファイリング（React DevTools フック）、ヒープサンプリング、レンダリング追跡
test-recorder	7	操作を記録し、Appium、Maestro、または Detox のテストを生成
filesystem	5	アプリのサンドボックスディレクトリ（Documents、キャッシュ、SQLite DB）内のファイルを参照、読み取り
devtools	1	CDP プロキシ経由で MCP と並行して Chrome DevTools を開く
debug-globals	1	Redux ストア、Apollo Client、その他のデバッグ用グローバルを自動検出
inspect-point	1	座標に基づく React コンポーネントの確認（実験的）
statusline	1	Claude Code ステータスバーとの統合

→ ツールの全リファレンスを参照してください。

---

Chrome DevTools

Hermes（React Native の JavaScript エンジン）は、一度に単一の CDP デバッガー接続しか許可しません。metro-mcp がその接続を使用するため、Metro で「j」を押すか、開発メニューで**「Open Debugger」**をタップすると、接続が奪われて MCP が切断されます。

metro-mcp は、組み込みのCDP プロキシで単一の Hermes 接続を多重化することでこの問題を解決し、Chrome DevTools と MCP を同時に使用できるようにします。

DevTools を開く

通常の方法ではなく、open_devtools MCP ツールを使用してください。このツールは、Metro が使用するものと同じ React Native DevTools フロントエンド（rn_fusebox）を開きますが、WebSocket 接続をプロキシ経由にすることで、両方を併用できるようにします。

このツールは Metro と同じ検出方法で Chrome または Edge を自動的に見つけ、独立した DevTools ウィンドウを開きます。

避けること

方法	起こること
Metro ターミナルで "j" を押す	MCP が切断されます
開発メニューで "Open Debugger" を選ぶ	MCP が切断されます
open_devtools MCP ツール	MCP と併用できます

設定

CDP プロキシはデフォルトで有効になっています。ポートを変更するか、無効にするには：

# Set a fixed proxy port
METRO_MCP_PROXY_PORT=9222 npx metro-mcp

# Disable the proxy entirely
METRO_MCP_PROXY_ENABLED=false npx metro-mcp

---

Claude Code ステータスバー

Claude Code のステータスバーで、Metro CDP の接続状況をリアルタイムに確認できます。

Claude Code で setup_statusline を実行すると、~/.claude/metro-mcp-statusline.sh にスクリプトが書き込まれます。その後、ステータスバーに追加するよう Claude に依頼してください：

/statusline add the script at ~/.claude/metro-mcp-statusline.sh

ステータスバーの表示には、次の 3 つの状態があります：

状態	表示
実行されていない	Metro ○（暗い表示）
実行中、未接続	Metro ●（赤）
接続済み	Metro ● localhost:8081（緑）

---

テスト記録

実際のユーザー操作（タップ、テキスト入力、スクロール）を記録し、本番環境で使えるテストを生成します。アプリのコード変更は不要です。

AI によるテスト生成

フローを説明すると、AI がアプリを操作してテストを生成します：

「ゲストチェックアウトのフローをテストする Appium テストを書いてください。ウェルカム画面で『Start Shopping』をタップして開始し、カート画面が表示されたら終了してください。」

AI は start_test_recording を呼び出し、tap_element／type_text／swipe を使って操作します。その後、ファイバーツリーから取得した実際のセレクターを使って、完全なテストを生成します。

手動記録

start_test_recording   → inject interceptors
(interact with the app)
stop_test_recording    → retrieve event log
generate_test_from_recording format=appium

Appium（WebdriverIO）、Maestro YAML、Detox に対応しています。

→ 詳細、形式の例、ヒントについては、テストガイドをご覧ください。

---

アプリ統合（任意）

カスタムコマンドを登録して状態を MCP サーバーに公開できます。パッケージは不要です。開発モードで、アプリのエントリーポイントに次のコードを追加してください：

if (__DEV__) {
  globalThis.__METRO_BRIDGE__ = {
    commands: {
      // Run custom actions from the MCP client
      login: async ({ email, password }) => {
        return await authService.login(email, password);
      },
      resetOnboarding: () => {
        AsyncStorage.removeItem('onboarding_completed');
      },
      switchUser: ({ userId }) => {
        store.dispatch(switchUser(userId));
      },
    },
    state: {
      // Expose state snapshots readable via get_redux_state
      userStore: () => useUserStore.getState(),
    },
  };
}

list_commands と run_command を使って、MCP クライアントからこれらを呼び出します。

Redux アクションのリアルタイム追跡、ナビゲーションイベント、パフォーマンスマーク、React のレンダリングプロファイリングなどの拡張機能を使うには、metro-bridge をインストールしてください。クライアント SDK ドキュメントとプロファイリングガイドをご覧ください。

---

設定

環境変数、CLI 引数、設定ファイルのオプションについては、設定ドキュメントをご覧ください。

---

カスタムプラグイン

metro-mcp は完全に拡張可能です。独自のツールやリソースを作成するには、プラグインガイドをご覧ください。

---

互換性

• React Native：0.70 以降（Hermes が必要）
• Expo：SDK 49 以降
• ランタイム：Node.js 18 以降、または Bun 1.0 以降
• プラットフォーム：iOS シミュレーター、Android エミュレーター、USB 接続の実機

ライセンス

MIT