Expo Agent Bridge

网站 · 文档 · 工具参考 · 一键 AI 设置 · 更新日志

---

expo-mcp-bridge 让 AI Agent（Claude Code、Antigravity、Cursor 以及任何其他 MCP 客户端）能够在实时运行于你真实手机上的 Expo / React Native 应用中观察和操作。Agent 可以读取屏幕、点击、输入、滚动、截图、读取控制台错误和网络请求，还能按下硬件按键。不必再把截图粘贴到聊天中。

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

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

“打开应用，尝试使用错误输入填写注册表单，然后告诉我哪里出问题了。”

目录

• 安装
• 快速开始
• 功能
• Agent 能看到什么
• 常见问题
• 连接你的 Agent
• 工具
• 组件 API
• CLI 和环境
• 工作原理
• 故障排除
• 限制
• 相关内容
• 参与贡献
• 许可证

安装

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

react-native-view-shot 为截图提供支持，并随 Expo Go 一同提供；在自定义开发构建中安装后，只需重新构建一次客户端。init 会写入 Agent 的 MCP 配置、安装 Agent 技能，并将指南添加到 AGENTS.md。

要求： 电脑上安装 Node.js 20 或更高版本 · 一个 Expo（或 React Native）应用 · 手机和电脑连接到同一 Wi-Fi。

快速开始

一键方式。 在 Expo 项目中将以下内容粘贴到 Claude Code、Antigravity 或 Cursor，Agent 会自行安装、挂载并验证所有内容：

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

手动操作，两分钟完成：

1. 安装软件包并运行 init（见上文）。
2. 挂载一次 <AgentBridge />，将其放在根布局的最后一个子项位置（示例见本页顶部）。
3. 以 LAN 模式运行 npx expo start，然后在手机上打开应用。
4. 重启 Agent，让它在应用中执行某项操作。

功能

• 真实设备，无需原生配置。 使用 Expo Go 或开发构建版本，通过 Wi-Fi 连接 iPhone 或 Android 设备。只需一个组件，无需链接原生代码。
• 设计上节省 Token。 Agent 读取的是可见屏幕的精简概览——约 70 个 Token，而截图约需 1,000 个 Token；每次操作只返回发生变化的内容。
• 快速完成工作流。 UI 稳定后，操作立即完成。app_batch 一次调用即可填写整个表单。
• 发现出错之处。 新出现的 JS 错误和失败的请求会附加到导致它们的操作上。
• 全面掌控。 点击、输入、滚动、切换、导航、等待、截图、布局、日志、网络、求值，以及音量／返回／主页按键。
• 内置 Agent 技能。 init 会为 Claude Code 安装技能，并为 Antigravity、Cursor、Codex 等工具安装 AGENTS.md 指南，让 Agent 从第一条消息起就能熟练使用这些工具。
• 仅用于开发。 在生产构建版本中，<AgentBridge /> 只渲染其子元素，不做其他操作。

Agent 看到的内容

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 />。随后，Agent 就可以使用 app_snapshot（读取可见屏幕）、app_tap、app_type 和 app_screenshot 等 MCP 工具，直接操作手机上运行的应用。

我的 AI Agent 总是让我提供 React Native 应用的截图。怎样才能避免？

这个软件包正是为了解决这个问题。Agent 无需再让你截图并粘贴到聊天中，而是会自行调用 app_snapshot，接收屏幕的精简概览（约 70 个 Token，而图像约需 1,000 个 Token）；确实需要像素信息时，也可以调用 app_screenshot。

AI Agent 能在真实手机上测试我的 React Native 应用吗？

可以。Agent 会通过真实的处理程序点击、输入、滚动和导航；每次操作后读取新出现的 JS 错误和失败的网络请求，并报告出错之处。它可通过 Wi-Fi 在 iPhone 和 Android 设备上的 Expo Go 或开发构建版本中运行。

它支持 Expo Go 吗？

支持。桥接组件及其截图依赖项（react-native-view-shot）都能在 Expo Go 中运行。无需原生代码、配置插件或重新构建。

它与 Detox、Maestro 或 Appium 有什么区别？

这些是端到端测试框架：你需要编写测试脚本或工作流，并在 CI 中运行。expo-mcp-bridge 用于与 AI Agent 协同开发：Agent 会交互式地探索并驱动正在运行的应用，并在同一会话中修复代码。它无需原生配置，而且可以直接读取 React 树，因此它是测试框架的补充，而非替代品。

将它留在应用中安全吗？

<AgentBridge /> 只会在开发环境（__DEV__）中运行，并且只连接到你自己的计算机。在生产构建版本中，它只渲染其子元素，不做其他操作。

连接 Agent

init 会为 Claude Code 写入 .mcp.json。其他 Agent 也使用同一服务：

Agent	配置
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	可见屏幕的轮廓，包含稳定的 ref（[e3]）
app_screenshot	可见屏幕的 JPEG；使用 saveTo 保存到文件；使用 fullScroll 将整页捕获为一张长图
app_layout	元素位置（dp）和字体大小

操作

工具	描述
app_tap	按 ref、testID 或文本点击（长按时设为 long: true）
app_type	填写输入框（submit、append）
app_batch	在一次调用中执行多次点击、输入、滚动和导航
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 bundle，并如实说明是否未能重新加载

设备

工具	描述
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> 一致）

通常无需自行运行服务端——Agent 会通过 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	另一个 Agent 会话正在运行服务端——请关闭该会话，或设置 EXPO_MCP_PORT 和 port 属性。
Metro：Unable to resolve "expo-mcp-bridge"	运行 npx expo start --clear
app_reload 无法重新加载	Metro 已重启；摇动手机，然后选择一次 Reload。
截图失败	安装 react-native-view-shot（如果使用开发客户端，请重新构建）。

更多信息请参阅故障排除指南。

限制

应用内库只能控制你自己的应用；OS 会阻止操作系统对话框和其他应用。Android 上的 device_key 可通过 adb 操作硬件按键。仅存在于原生代码中的手势（例如没有 onPress 的平移处理程序）无法通过 JavaScript 触发。

相关项目

• expo-launch-video — 基于此桥接工具构建：你的 Agent 可通过手机实时录制应用，并在可通过提示词操控的工作室中，剪辑出包含动态图形、弹出效果和音效的发布视频。
• Expo Agent Kit — 两个库的网站和完整文档。

贡献

npm install
npm test

测试会在 Node 中运行此桥接工具，并连接到真实的 MCP 服务。详情请参阅 CONTRIBUTING.md。

许可证

MIT © Rudra Samadhiya