react-native-eye

React Native MCP 服务器 · iOS 与 Android

让你的编程智能体看见它正在开发的应用。

react-native-eye 把 Claude Code、Cursor 或任何 MCP 客户端连接到正在运行的 React Native 应用。智能体可以读取屏幕、点击和输入，并检查日志、网络和状态。它通过 Metro 工作，应用无需接入 SDK，也无需改动代码。

添加到 Claude Code

claude mcp add react-native-eye -- npx -y react-native-eye@latest
Cursor、Codex 及其他客户端
  • 35 个工具
  • iOS 模拟器、Android 模拟器
  • 无遥测
  • MIT

屏幕

Welcome back Email Password Log in Forgot password? Create account

智能体读到的内容

› observe
LAYOUT (js):
ERRORS:
none
LOGS:
[log] auth: no saved session
› get_layout {"search": ["Log in"]} Log in @196,468 (layout: js)

登录页面的示例输出。把鼠标移到某一行即可找到对应元素。

一次调用完成整个流程

大多数设备工具每点一次，智能体就要与模型往返一次。在这里，智能体一次发出所有步骤，由服务器连续执行。出现 redbox 或未捕获的异常时流程立即停止，智能体会拿到每一步的结果。

  • observe截图、可交互元素、最近的错误和日志。
  • run_flow点击、输入、等待和断言，全部在服务器上执行。
  • check_state当前路由、store 状态和未处理的错误。
请求 · run_flow
{ "steps": [
  { "type": { "text": "a@b.c", "into": { "placeholder": "Email" } } },
  { "type": { "text": "hunter2", "into": { "placeholder": "Password" } } },
  { "tap": { "text": "Log in", "via": "os" } },
  { "wait_for": { "text": "Home", "timeout_ms": 3000 } },
  { "expect_not": { "text": "Error" } }
] }
响应
Flow completed.

1. type({"text":"a@b.c","into":{"placeholder":"Email"}}) — ok (input: js)
2. type({"text":"hunter2","into":{"placeholder":"Password"}}) — ok (input: js)
3. tap({"text":"Log in","via":"os"}) — ok (input: os/runner)
4. wait_for({"text":"Home","timeout_ms":3000}) — ok
5. expect_not({"text":"Error"}) — ok

智能体能做什么

35 个工具，分为五组。每个响应都会说明实际走的路径，不会悄悄切换。

  • 查看屏幕

    元素位置取自应用的 JS 运行时，约 80 毫秒。OCR 能读到组件树里没有的内容：图片、WebView 和原生对话框。

    observescreenshotget_layoutread_screen_textget_component_tree

  • 执行操作

    JS 点击直接调用元素自身的 onPress，约 1 毫秒。真实触摸由设备上的驱动完成，用于手势、系统对话框和原生视图。

    run_flowtaptype_textswipescroll_topress_keynavigateopen_url

  • 调试

    日志、带请求体的网络请求、store 状态和 JS 求值。被 LogBox 吞掉的崩溃同样会上报。

    check_stateget_logsget_errorsget_networkget_stateeval_jsget_job

  • 测量

    哪些组件渲染了以及原因、Hermes CPU 分析、各线程 CPU 占用和帧耗时。应用内无需任何配置。

    profile_rendersprofile_jssample_cpuget_fps

  • 管理设备

    安装、启动和重新加载应用，授予权限，录制视频。

    connectlist_targetslist_deviceslaunch_appreload_appinstall_appopen_simulatorset_permissionrecord_videostop_recordingping

组合工具：一次调用代替多次调用。

进入应用的两条路径

服务器通过两条路径访问应用，并为每次调用选择代价更低的一条。

你的智能体Claude Code, Cursor, Codex
MCP · stdio
react-native-eye运行在你的电脑上
CDP · Metro
JS 运行时（Hermes）布局、点击、输入、日志、网络、状态
HTTP · localhost
设备上的驱动真实触摸、按键、系统视图层级、截图

通过 JS 运行时

每次点击 ≈ 1 毫秒 · 整屏布局 ≈ 80 毫秒

服务器通过 Chrome DevTools Protocol 遍历 React 的 fiber 树，测量元素并直接调用点击和文本处理函数，全程不产生触摸事件。

通过设备

已预编译并随 npm 包发布 · 首次使用时自动安装

iOS 上的 XCUITest runner 和 Android 上的 instrumentation 服务器负责发送真实触摸，并可输入任意 Unicode 文本。驱动无法启动时，输入会回退到 axe 或 adb，响应中会注明。

实测：设备驱动与它所替代的工具

iOS 模拟器。滑动一次信息流，40 次的中位数。
驱动
0.93 s
axe
26.68 s
40 次中有 3 次在 90 秒时超时
Android 模拟器。视频播放时读取视图层级，10 次的中位数。
驱动
4.60 s
uiautomator
27.10 s
10 次中有 9 次失败

数据来自项目自身的实地测试，测试对象是高负载的视频信息流，环境为 iOS 26 模拟器和 Android 16 模拟器。两张图使用同一比例尺。

三步完成接入

  1. 把服务器添加到你的客户端

    # 在你的项目目录下
claude mcp add react-native-eye -- npx -y react-native-eye@latest

  2. 启动 Metro 和开发版应用

    像平时一样在 iOS 模拟器或 Android 模拟器中运行应用。8081–8083 和 19000–19002 端口上的 Metro 会被自动发现。如果使用其他端口，请在参数中加上 --port 8090。

  3. 向智能体提问

    连接到我的应用，告诉我屏幕上有什么。

    智能体会先调用 connect，再调用 observe。在每台设备上首次调用时会安装一次驱动。

无遥测。 无账号。 无云端。

所有网络流量只发往 localhost：Metro 和设备驱动。只要服务器源码中出现外部 URL，测试就会让构建失败。

须知

  • 仅支持开发版构建。生产版构建没有可供连接的 Metro。
  • 已在 iOS 模拟器和 Android 模拟器上测试。
  • React Native 0.85 以下同一时间只允许一个调试器，请先关闭其他调试器。

React Native MCP 服务器：常见问题

什么是 React Native MCP 服务器？
MCP 服务器为 AI 编程智能体提供可调用的工具。React Native MCP 服务器把这些工具连到正在运行的 React Native 应用上，让智能体在写代码的同时读取屏幕、点击、输入，并检查日志、网络请求和状态。react-native-eye 通过 Metro 实现这一点，应用里无需接入 SDK。
它支持哪些 AI 智能体？
Claude Code、Cursor、Codex、Claude Desktop，以及任何通过 stdio 运行 MCP 服务器的客户端。
它支持 Expo 吗？
支持。它适用于 Expo SDK 54+ 和 React Native 0.70+ 的开发版构建，需要 Metro 和 Hermes 正在运行。
需要修改应用代码吗？
不需要。服务器连接的是 Metro 本来就提供的调试端点。另有一行可选代码 globalThis.__RNE_STORES__ = …，能让读取 store 状态更方便。
iOS 和 Android 都能用吗？
可以：macOS 上的 iOS 模拟器，以及通过 adb 连接的 Android 模拟器。需要开发版构建，生产版构建没有可供连接的 Metro。
它免费吗？
免费。它以 MIT 许可证发布，无需账号，没有调用次数限制，也没有遥测。