Expo Agent Bridge

io.github.RudrasamadhiyaPublished by GitHub account Rudrasamadhiyav0.3.2Updated Oct 29, 2026

Let AI agents see, tap, type, scroll, screenshot and debug your Expo app on a real phone.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

Bridges an AI agent into a live Expo/React Native app on a real phone so it can read the screen, tap, type, scroll, screenshot and debug.

What you can do
  • Inspect the connected app: connection and device status, a compact text outline of the visible screen with element refs, element positions and font sizes, JPEG screenshots.
  • Drive the UI: tap, type into inputs, scroll lists, toggle switches, navigate routes or deep links, wait for elements, dismiss the keyboard, and batch several actions in one call.
  • Debug: read console logs and JS errors, inspect fetch/XHR requests with status and timing, run JavaScript inside the app, reload the JS bundle.
  • Press Android hardware and system keys such as volume, back, home and power via adb.
When to use it
Useful when developing an Expo or React Native app and you want the agent to explore the running app on a real device, fill in forms, reproduce a bug, or check what broke after an action, instead of you pasting screenshots into the chat. It complements end-to-end test frameworks rather than replacing them.
Requirements
Node.js 20 or newer on the computer, an Expo or React Native app with the AgentBridge component mounted in the root layout, and the expo-mcp-bridge and react-native-view-shot packages installed. Phone and computer must be on the same Wi-Fi in LAN mode; the EXPO_MCP_PORT variable (default 8347) must match the component's port prop. Android hardware keys need adb over USB or Wi-Fi debugging.
Before you install
The bridge calls the app's real handlers, so taps and typing change app state and can submit forms or trigger requests. app_eval runs arbitrary JavaScript inside the app and is enabled by default; it can be turned off with the allowEval prop. Logs and network bodies, including request payloads, are exposed to the agent. The bridge is meant for development only and is inert in production builds.

Installation

In SourceWeft

  1. Open Expo Agent Bridge in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[expo-mcp-bridge — let your AI agent use your phone app the way it uses a browser]

[npm version] [CI] [node] [MIT license]

Website · Docs · Tools reference · One-shot AI setup · Changelog

expo-mcp-bridge gives AI agents — Claude Code, Antigravity, Cursor and any other MCP client — eyes and hands inside your Expo / React Native app, running live on your real phone. The agent reads the screen, taps, types, scrolls, takes screenshots, reads console errors and network requests, and presses hardware keys. No more pasting screenshots into the chat.

tsx
import { Stack, router } from 'expo-router';import { AgentBridge } from 'expo-mcp-bridge';
export default function RootLayout() {  return (    <>      <Stack />      <AgentBridge router={router} />    </>  );}

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

Table of contents

Installation

bash
npx expo install expo-mcp-bridge react-native-view-shotnpx expo-mcp-bridge init

react-native-view-shot powers screenshots and ships with Expo Go; in a custom dev build, rebuild the client once after installing it. init writes your agent's MCP config, installs the agent skill and adds a guide to AGENTS.md.

Requirements: Node.js 20 or newer on your computer · an Expo (or React Native) app · phone and computer on the same Wi-Fi.

Quick start

The one-shot way. Paste this into Claude Code, Antigravity or Cursor inside your Expo project and the agent installs, mounts and verifies everything itself:

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

By hand, in two minutes:

  1. Install the packages and run init (above).
  2. Mount <AgentBridge /> once, as the last child of your root layout (example at the top of this page).
  3. Run npx expo start in LAN mode and open the app on your phone.
  4. Restart your agent and ask it to do something in the app.

Features

  • Real devices, zero native setup. Expo Go or a dev build, iPhone or Android, over Wi-Fi. One component, no native linking.
  • Token-cheap by design. The agent reads a compact outline of the visible screen — about 70 tokens instead of about 1,000 for a screenshot — and every action returns only what changed.
  • Fast flows. Actions finish the moment the UI settles. app_batch fills a whole form in one call.
  • Sees what broke. New JS errors and failed requests are attached to the action that caused them.
  • Full control. Tap, type, scroll, toggle, navigate, wait, screenshots, layout, logs, network, eval — and volume / back / home keys.
  • Agent skill included. init installs a skill for Claude Code and an AGENTS.md guide for Antigravity, Cursor, Codex and others, so agents use the tools well from the first message.
  • Dev only. In production builds <AgentBridge /> renders its children and nothing else.

What the agent sees

A real login screen, as returned by app_snapshot:

text
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]

Tapping e5 (show password) returns just the difference:

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

Common questions

How do I let Claude Code, Cursor or Antigravity see my Expo app?

Install this package, run npx expo-mcp-bridge init, and mount <AgentBridge /> in your root layout. Your agent then gets MCP tools such as app_snapshot (read the visible screen), app_tap, app_type and app_screenshot, and works directly against the app running on your phone.

My AI agent keeps asking me for screenshots of my React Native app. How do I stop that?

That is exactly what this package replaces. Instead of you taking screenshots and pasting them into the chat, the agent calls app_snapshot itself and receives a compact outline of the screen (about 70 tokens instead of about 1,000 for an image), or app_screenshot when it really needs pixels.

Can an AI agent test my React Native app on a real phone?

Yes. The agent taps, types, scrolls and navigates through your real handlers, reads new JS errors and failed network requests after every action, and reports what broke. It works in Expo Go or a dev build, on iPhone and Android, over Wi-Fi.

Does it work with Expo Go?

Yes. Both the bridge and its screenshot dependency (react-native-view-shot) run in Expo Go. No native code, no config plugin and no rebuild are needed.

How is this different from Detox, Maestro or Appium?

Those are end-to-end test frameworks: you write test scripts or flows and run them in CI. expo-mcp-bridge is for development with an AI agent: the agent explores and drives the live app interactively and fixes the code in the same session. It needs no native setup and reads the React tree directly, so it complements a test framework rather than replacing one.

Is it safe to leave in my app?

<AgentBridge /> only runs in development (__DEV__) and only connects to your own computer. In production builds it renders its children and nothing else.

Connecting your agent

init writes .mcp.json for Claude Code. Other agents use the same server:

AgentConfiguration
Claude Code.mcp.json from init, or claude mcp add expo-app -- npx expo-mcp-bridge
Cursornpx expo-mcp-bridge init --cursor writes .cursor/mcp.json
Antigravity, Windsurf, ClineMCP settings: {"mcpServers": {"expo-app": {"command": "npx", "args": ["expo-mcp-bridge"]}}}

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

Tools

Target elements by ref from a snapshot, by testID, or by visible text. Full parameters are in the tools reference.

Read

ToolDescription
app_statusConnected device, OS, screen size, SDK
app_snapshotOutline of the visible screen with stable refs ([e3])
app_screenshotJPEG of the visible screen; saveTo a file; fullScroll for the whole page as one tall image
app_layoutElement positions (dp) and font sizes

Act

ToolDescription
app_tapPress by ref, testID or text (long: true for a long press)
app_typeFill an input (submit, append)
app_batchSeveral taps, types, scrolls and navigations in one call
app_scrollScroll down, up, left, right, to the top or bottom
app_toggleFlip or set a Switch
app_navigateOpen an expo-router path or deep link (replace keeps the stack shallow)
app_waitWait for text or a testID to appear or disappear
app_dismiss_keyboardHide the on-screen keyboard

Debug

ToolDescription
app_logsConsole logs and JS errors (cursor-based)
app_networkfetch / XHR requests with status, timing and bodies
app_evalRun JavaScript inside the app (dev only)
app_reloadReload the JS bundle, and say honestly if it couldn't

Device

ToolDescription
device_keyvolume_up, volume_down, mute, back, home, power and more (Android, via adb)

Component API

tsx
<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/>
PropTypeDefaultDescription
routerexpo-router router—Used by app_navigate for exact navigation
hoststringfrom MetroComputer running the MCP server
portnumber8347WebSocket port; must match EXPO_MCP_PORT
allowEvalbooleantrueAllow app_eval
enabledbooleantrue in devTurn the bridge on or off

CLI and environment

bash
npx expo-mcp-bridge init            # .mcp.json + agent skill + AGENTS.md sectionnpx expo-mcp-bridge init --cursor   # also write .cursor/mcp.jsonnpx expo-mcp-bridge                 # run the MCP server (your agent starts this for you)npx expo-mcp-bridge --help
VariableDefaultDescription
EXPO_MCP_PORT8347WebSocket port the phone connects to (match <AgentBridge port>)

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

How it works

text
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 and 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.

Troubleshooting

SymptomFix
No app connectedSame Wi-Fi, LAN mode (not --tunnel), firewall allows Node on 8347, <AgentBridge /> mounted. USB-only Android: adb reverse tcp:8347 tcp:8347 and host="localhost".
Port 8347 is already in useAnother agent session runs the server — close it, or set EXPO_MCP_PORT and the port prop.
Metro: Unable to resolve "expo-mcp-bridge"npx expo start --clear
app_reload can't reloadMetro was restarted; shake the phone and choose Reload once.
Screenshots failInstall react-native-view-shot (rebuild the dev client if you use one).

More in the troubleshooting guide.

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 JavaScript.

Related

  • expo-launch-video — builds on this bridge: your agent records the app live from the phone and cuts a launch video with motion graphics, pop-outs and sound, in a studio you can prompt.
  • Expo Agent Kit — the website and full documentation for both libraries.

Contributing

bash
npm installnpm test

The tests run the bridge in Node against the real MCP server. See CONTRIBUTING.md for details.

License

MIT © Rudra Samadhiya

Source: README.md at commit 6f03ca7

Tools

17

app_status

Check whether the mobile app is connected and show device info. Call first.

Takes no parameters.

app_snapshot

Compact text outline of the current screen (buttons, inputs, text, lists) with refs like [e3] to act on. Prefer this over screenshots.

ParametersmaxLines

app_layout

Positions (dp, window coordinates) and font sizes of elements on the current screen. For layout checks and visual work; app_snapshot is cheaper for acting.

Parameterslimit

app_screenshot

JPEG screenshot of the app. Use only for visual/layout questions; app_snapshot is cheaper for finding elements. With saveTo, writes the file and returns only its path (no image tokens).

ParametersareasaveToqualitymaxWidthfullScroll

app_batch

Run several actions in one call (fastest way to fill forms or walk a flow). Returns the screen once at the end. Steps: {action:"tap"|"type"|"scroll"|"toggle"|"navigate"|"wait"|"dismiss_keyboard", ...that tool's args}.

Parametersfullstepsrequiredsnapshot

app_tap

Press a button/pressable element. Returns what changed on screen plus any new errors.

ParametersreffulllongtexttestIDsnapshot

app_type

Set text in an input (replaces by default). Target by ref, testID, or placeholder text.

ParametersreffulltextvaluerequiredappendsubmittestIDsnapshot

app_scroll

Scroll a list/ScrollView (first one on screen if no target).

ParametersreffulltextamounttestIDsnapshotdirection

app_toggle

Flip a Switch (or set it with value).

ParametersreffulltextvaluetestIDsnapshot

app_navigate

Open a route (expo-router path like "/settings") or a full deep link.

Parametersfullpathrequiredreplacesnapshot

app_wait

Wait until text or a testID appears (or disappears with gone=true). Cheaper than polling snapshots.

ParametersgonetexttestIDtimeout

app_logs

Console logs and JS errors captured in the app.

Parametersclearlevellimitsincesearch

app_network

HTTP requests made by the app (fetch/XHR) with status, timing and truncated bodies.

ParameterslimitsincebodiessearchfailedOnly

app_eval

Run JavaScript inside the app (dev only) and return the JSON result. Expression or statements with return. `bridge` and `RN` (react-native) are in scope.

Parameterscoderequired

app_reload

Reload the JS bundle (like pressing r in Metro).

Takes no parameters.

app_dismiss_keyboard

Hide the on-screen keyboard.

Takes no parameters.

device_key

Press a hardware/system key on an Android device via adb (USB or Wi-Fi debugging): volume_up, volume_down, mute, back, home, app_switch, enter, tab, delete, power, menu, escape.

Parameterskeyrequiredrepeat

Version history

1
  1. v0.3.2LatestOct 21, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts