Rudrasamadhiya/expo-mcp-bridge

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 (
<>
);
> "Open the app, try the sign-up form with bad input, and tell me what breaks."
## Table of contents
Installation
Quick start
Features
What the agent sees
Common questions
Connecting your agent
Tools
Component API
CLI and environment
How it works
Troubleshooting
Limits
Related
Contributing
License
## Installation
bash
npx expo install expo-mcp-bridge react-native-view-shot
npx 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/AISETUP.md and set it up in this project.
By hand, in two minutes:
1. Install the packages and run init (above).
2. Mount 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. appbatch 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 renders its children and nothing else.
## What the agent sees
A real login screen, as returned by appsnapshot:
text
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]
Tapping e5 (show password) returns just the difference:
text
Tapped.
Changes (+ added, - removed):
~ input "••••••••" value="" [e4]
button "icon:eye-off" [e9]