expo-mcp-bridge

Let your AI agent use your phone app the way it uses a browser.

Claude Code, Antigravity, Cursor and any other MCP agent can read the screen, tap, type and fill forms, scroll, take screenshots, read console errors and network requests, and press volume / back / home in your Expo / React Native app, running live in Expo Go on your real phone. No more pasting screenshots into the chat.

• 📱 Real devices, zero native setup — Expo Go or a dev build, iPhone or Android, over Wi-Fi.

• 🪶 Token-cheap — the agent reads a compact outline of the visible screen; every action returns only what changed.

• ⚡ Fast — actions finish as soon as the UI settles; app_batch runs a whole flow in one call.

• 🔎 Sees what's broken — new JS errors and failed requests are attached to the action that caused them.

• 🤖 Skill included — init installs an agent skill (Claude Code) and an AGENTS.md guide (Antigravity, Cursor, Codex…).

• 🔒 Dev only — in production builds <AgentBridge /> renders its children and nothing else.

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

What the agent sees of a real login screen: ~70 tokens instead of ~1,000 for a screenshot. Tapping e5 returns just:

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

🚀 Quick start

Option A — let your AI do it (one shot)

Paste this to Claude Code, Antigravity or Cursor inside your Expo project:

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

Option B — by hand (2 minutes)

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

Mount the bridge once in your root layout (app/_layout.tsx):

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

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

Run npx expo start (LAN mode), open the app on your phone (same Wi-Fi), restart your agent and ask:

"Open the app, try the sign-up form with bad input, and tell me what breaks."

Agent configuration

init writes .mcp.json (Claude Code). Other agents:

On Windows: "command": "cmd", "args": ["/c", "npx", "expo-mcp-bridge"].

Related MCP server: React Native Debug MCP

🧰 Tools

💻 CLI

npx expo-mcp-bridge init            # in your Expo project: .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 from .mcp.json)
npx expo-mcp-bridge --help

You normally never run the server yourself — the agent launches it over stdio. To try it by hand, any MCP client works, e.g. npx @modelcontextprotocol/inspector npx expo-mcp-bridge.

⚙️ Props

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

🔧 How it works

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

The in-app component reads React's live component tree, so it sees exactly what you rendered: your testIDs, labels, inputs and lists. It calls your real onPress / onChangeText handlers, so app logic runs exactly as if a user did it. Native-stack screens hidden under the current one are skipped, modals are captured as overlays, and screenshots capture the visible screen view (whole-window capture can return stale frames on Android).

🩺 Troubleshooting

🎬 Make launch videos too

expo-launch-video builds on this bridge: your agent records the app live from the phone and edits a launch video with motion graphics, pop-outs and sound, in a browser studio you can prompt.

Limits

An in-app library controls your own app only; the OS blocks system dialogs and other apps. device_key covers hardware keys via adb on Android. Gestures that exist only in native code (a pan handler with no onPress) can't be triggered from JS.

Contributing

npm install && npm test — the bridge runs in Node against the real MCP server. See CONTRIBUTING.md. MIT licensed.