Expo Agent Bridge

ウェブサイト · ドキュメント · ツールのリファレンス · ワンショット AI セットアップ · 変更履歴

---

expo-mcp-bridge を使うと、Claude Code、Antigravity、Cursor など、あらゆる MCP クライアントから AI エージェントが、実際のスマートフォンで実行中の Expo／React Native アプリを操作できます。エージェントは画面を読み取り、タップ、入力、スクロール、スクリーンショットの撮影、コンソールエラーやネットワークリクエストの読み取り、ハードウェアキーの押下を行えます。チャットにスクリーンショットを貼り付ける必要はもうありません。

import { Stack, router } from 'expo-router';
import { AgentBridge } from 'expo-mcp-bridge';

export default function RootLayout() {
  return (
    <>
      <Stack />
      <AgentBridge router={router} />
    </>
  );
}

「アプリを開いて、サインアップフォームに不正な入力を試し、何が問題になるか教えてください。」

目次

• インストール
• クイックスタート
• 機能
• エージェントに見えるもの
• よくある質問
• エージェントの接続
• ツール
• コンポーネント API
• CLI と環境
• 仕組み
• トラブルシューティング
• 制限事項
• 関連項目
• コントリビューション
• ライセンス

インストール

npx expo install expo-mcp-bridge react-native-view-shot
npx expo-mcp-bridge init

スクリーンショットの撮影には react-native-view-shot を使用します。Expo Go に同梱されています。カスタム開発ビルドでは、インストール後に一度クライアントを再ビルドしてください。init はエージェントの MCP 設定を書き込み、エージェントスキルをインストールし、AGENTS.md にガイドを追加します。

要件： コンピューターに Node.js 20 以降 · Expo（または React Native）アプリ · 同じ Wi-Fi に接続したスマートフォンとコンピューター

クイックスタート

ワンショットで行う方法。 Expo プロジェクト内で Claude Code、Antigravity、または Cursor に以下を貼り付けると、エージェントがすべてを自動でインストール、マウント、検証します。

Read https://raw.githubusercontent.com/Rudrasamadhiya/expo-mcp-bridge/main/AI_SETUP.md and set it up in this project.

手動で行う場合、2 分で完了します：

1. パッケージをインストールして、init を実行します（上記を参照）。
2. ルートレイアウトの最後の子として <AgentBridge /> を一度マウントします（このページ上部の例を参照）。
3. LAN モードで npx expo start を実行し、スマートフォンでアプリを開きます。
4. エージェントを再起動し、アプリで何かを実行するよう依頼します。

機能

• 実機で、ネイティブのセットアップは不要です。 Expo Go または開発ビルドを使い、Wi-Fi 経由で iPhone または Android に接続します。コンポーネントは 1 つだけで、ネイティブのリンク作業も不要です。
• トークン消費を抑える設計です。 エージェントが読み取るのは、表示中の画面の簡潔なアウトラインです。スクリーンショットの約 1,000 トークンに対し、約 70 トークンで済みます。また、各アクションが返すのは変更点だけです。
• 操作の流れがスムーズです。 UI が落ち着いた時点でアクションが完了します。app_batch を使えば、1 回の呼び出しでフォーム全体に入力できます。
• 問題の発生箇所を確認できます。 新たな JS エラーやリクエストの失敗は、それらを引き起こしたアクションに紐付けられます。
• 完全に制御できます。 タップ、入力、スクロール、切り替え、画面遷移、待機、スクリーンショット、レイアウト、ログ、ネットワーク、評価に加え、音量／戻る／ホームキーを操作できます。
• エージェントスキルが含まれています。 init は Claude Code 用のスキルと、Antigravity、Cursor、Codex などに対応した AGENTS.md ガイドをインストールするため、エージェントは最初のメッセージからツールを効果的に使えます。
• 開発時のみ動作します。 本番ビルドでは、<AgentBridge /> は子要素だけをレンダリングします。

エージェントに表示される内容

app_snapshot が返す実際のログイン画面：

scroll [e1]
  button "icon:chevron-back" [e2]
  text "Welcome back"
  input "[email protected]" value="" [e3]
  input "••••••••" value="" (secure) [e4]
  button "icon:eye" [e5]
  button "Log In" [e7]

e5（パスワードを表示）をタップすると、差分だけが返されます：

Tapped.
Changes (+ added, - removed):
~ input "••••••••" value="" [e4]
+ button "icon:eye-off" [e9]
- button "icon:eye" [e5]

よくある質問

Claude Code、Cursor、Antigravity から Expo アプリを確認できるようにするには？

このパッケージをインストールして、npx expo-mcp-bridge init を実行し、ルートレイアウトに <AgentBridge /> を配置します。すると、エージェントは app_snapshot（表示中の画面を読み取る）、app_tap、app_type、app_screenshot などの MCP ツールを利用して、スマートフォン上で実行中のアプリを直接操作できます。

AI エージェントが React Native アプリのスクリーンショットを何度も要求します。どうすればやめさせられますか？

このパッケージは、まさにその状況を解消するものです。スクリーンショットを撮ってチャットに貼り付ける代わりに、エージェント自身が app_snapshot を呼び出し、画面の簡潔なアウトラインを受け取ります（画像の約 1,000 トークンに対し、約 70 トークン）。ピクセル単位の画像が本当に必要な場合は、app_screenshot を使います。

AI エージェントは実機で React Native アプリをテストできますか？

はい。エージェントは実際のハンドラーを通じてタップ、入力、スクロール、画面遷移を行い、各アクションの後に新たな JS エラーやネットワークリクエストの失敗を読み取り、問題の発生箇所を報告します。Expo Go または開発ビルドを使い、Wi-Fi 経由で iPhone と Android の両方で動作します。

Expo Go で動作しますか？

はい。ブリッジとスクリーンショットの依存関係（react-native-view-shot）は、どちらも Expo Go で動作します。ネイティブコードも、設定プラグインも、再ビルドも不要です。

Detox、Maestro、Appium とはどう違いますか？

これらはエンドツーエンドテスト用のフレームワークです。テストスクリプトやフローを作成し、CI で実行します。expo-mcp-bridge は、AI エージェントを使った開発向けです。エージェントが実行中のアプリを対話的に調べて操作し、同じセッション内でコードを修正します。ネイティブのセットアップは不要で、React ツリーを直接読み取るため、テストフレームワークの代わりではなく、併用するものです。

アプリに組み込んだままにしても安全ですか？

<AgentBridge /> は開発時（__DEV__）のみ動作し、お使いのコンピューターにのみ接続します。本番ビルドでは、子要素だけをレンダリングします。

エージェントの接続

init は Claude Code 用の .mcp.json を書き込みます。他のエージェントも同じサーバーを使用します。

エージェント	設定
Claude Code	init が生成する .mcp.json、または claude mcp add expo-app -- npx expo-mcp-bridge
Cursor	npx expo-mcp-bridge init --cursor を実行すると .cursor/mcp.json が生成されます
Antigravity、Windsurf、Cline	MCP 設定：{"mcpServers": {"expo-app": {"command": "npx", "args": ["expo-mcp-bridge"]}}}

Windows では "command": "cmd", "args": ["/c", "npx", "expo-mcp-bridge"] を使用してください。

ツール

スナップショットの ref、testID、または画面に表示されている text で要素を指定します。すべてのパラメーターはツールリファレンスをご覧ください。

読み取り

ツール	説明
app_status	接続中のデバイス、OS、画面サイズ、SDK
app_snapshot	表示画面の概要と、安定した参照（[e3]）
app_screenshot	表示画面の JPEG。saveTo でファイルに保存し、fullScroll でページ全体を縦長の1枚の画像として取得
app_layout	要素の位置（dp）とフォントサイズ

操作

ツール	説明
app_tap	ref、testID、またはテキストで押します（長押しするには long: true）
app_type	入力欄に入力します（submit、append）
app_batch	タップ、入力、スクロール、ナビゲーションを1回の呼び出しで複数実行
app_scroll	下、上、左、右、または先頭や末尾へスクロール
app_toggle	Switch の状態を切り替え、または設定
app_navigate	expo-router のパスまたはディープリンクを開きます（replace を使うとスタックを浅く保てます）
app_wait	テキストまたは testID の表示、または非表示を待ちます
app_dismiss_keyboard	画面上のキーボードを隠します

デバッグ

ツール	説明
app_logs	コンソールログと JS エラー（カーソルベース）
app_network	ステータス、タイミング、本文を含む fetch / XHR リクエスト
app_eval	アプリ内で JavaScript を実行（開発時のみ）
app_reload	JS バンドルを再読み込みします。できなかった場合は正直に伝えます

デバイス

ツール	説明
device_key	volume_up、volume_down、mute、back、home、power など（Android、adb 経由）

コンポーネント API

<AgentBridge
  router={router}      // expo-router's router, for exact app_navigate
  host="192.168.1.20"  // your computer's IP (auto-detected from Metro)
  port={8347}          // must match EXPO_MCP_PORT
  allowEval={false}    // disable app_eval
  enabled={false}      // turn the bridge off
/>

プロパティ	型	デフォルト	説明
router	expo-router router	—	app_navigate で正確なナビゲーションを行うために使用
host	string	Metro から取得	MCP サーバーを実行しているコンピューター
port	number	8347	WebSocket ポート。EXPO_MCP_PORT と一致させる必要があります
allowEval	boolean	true	app_eval を許可
enabled	boolean	開発時は true	ブリッジを有効または無効にします

CLI と環境

npx expo-mcp-bridge init            # .mcp.json + agent skill + AGENTS.md section
npx expo-mcp-bridge init --cursor   # also write .cursor/mcp.json
npx expo-mcp-bridge                 # run the MCP server (your agent starts this for you)
npx expo-mcp-bridge --help

変数	デフォルト	説明
EXPO_MCP_PORT	8347	スマートフォンの接続先となる WebSocket ポート（<AgentBridge port> と一致させます）

通常、サーバーを自分で実行する必要はありません。エージェントが stdio 経由で起動します。手動で試すには、どの MCP クライアントでも使用できます：npx @modelcontextprotocol/inspector npx expo-mcp-bridge。

仕組み

AI agent  ──MCP (stdio)──▶  expo-mcp-bridge server  ◀──WebSocket :8347──  <AgentBridge /> in your app

アプリ内コンポーネントは React のライブコンポーネントツリーを読み取るため、レンダリングした内容、つまり testID、ラベル、入力欄、リストをそのまま認識します。実際の onPress ハンドラーと onChangeText ハンドラーを呼び出すため、アプリのロジックはユーザーが操作した場合とまったく同じように実行されます。現在の画面の下に隠れている native-stack の画面はスキップされ、モーダルはオーバーレイとして取得されます。スクリーンショットには表示中の画面が収められます。

トラブルシューティング

症状	対処方法
No app connected	同じ Wi-Fi を使用し、LAN モード（--tunnel は使用しない）にします。ファイアウォールで Node の 8347 への接続を許可し、<AgentBridge /> をマウントします。USB 接続のみの Android の場合：adb reverse tcp:8347 tcp:8347 を実行し、host="localhost" を指定します。
Port 8347 is already in use	別のエージェントセッションがサーバーを実行しています。そのセッションを終了するか、EXPO_MCP_PORT と port プロパティを設定します。
Metro：Unable to resolve "expo-mcp-bridge"	npx expo start --clear
app_reload で再読み込みできない	Metro が再起動されています。スマートフォンをシェイクして、Reload を1回選択します。
スクリーンショットの取得に失敗する	react-native-view-shot をインストールします（開発クライアントを使用している場合は再ビルドします）。

詳しくはトラブルシューティングガイドをご覧ください。

制限事項

アプリ内ライブラリで操作できるのは、自分のアプリのみです。OS によってシステムダイアログや他のアプリへのアクセスはブロックされます。Android では、device_key が adb 経由でハードウェアキーに対応します。ネイティブコード内にしか存在しないジェスチャー（onPress のない pan handler など）は、JavaScript から実行できません。

関連プロジェクト

• expo-launch-video — このブリッジを基盤としており、エージェントがスマートフォンからアプリをリアルタイムで録画し、プロンプトで操作できるスタジオで、モーショングラフィックスやポップアウト、サウンドを加えたローンチ動画を作成します。
• Expo Agent Kit — 両ライブラリのウェブサイトおよび完全なドキュメントです。

コントリビューション

npm install
npm test

テストでは、実際の MCP サーバーに対して Node でブリッジを実行します。詳しくはCONTRIBUTING.mdをご覧ください。

ライセンス

MIT © Rudra Samadhiya