expo-headless-mcp

Name: expo-headless-mcp
Author: Abubakr-Sanginov

本地服务

github.com/Abubakr-Sanginov开发工具01 周前更新

代码仓库

关于 expo-headless-mcp

expo-headless-mcp 是用于检查和操作 Expo 与 React Native 应用的 MCP 服务，无需模拟器、手机或浏览器。它将界面渲染为 PNG，并支持交互和自动检查；也可选用设备控制。

主要功能

01将应用界面渲染为 PNG
02点击、输入和滚动
03检查元素布局与警告
04自动测试输入框和控件
05可选控制 Android 与 iOS 设备
06内置验证指引

适用场景

01代码更改后检查界面
02发现文字裁切和元素重叠
03查找崩溃和无响应控件
04在连接的 Android 设备上测试应用

MCP 相关

MCP 服务提供渲染和检查界面、与应用交互及运行自动化测试的工具。可选设备模式可操作 Android 设备或模拟器上的 Expo Go，以及已启动的 iOS Simulator，并须先获得同意。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "abubakr-sanginov-expo-headless": {
      "command": "npx",
      "args": [
        "-y",
        "expo-headless-mcp"
      ],
      "env": {
        "EXPO_PROJECT": "<EXPO_PROJECT>"
      }
    }
  }
}

启动命令npx -y expo-headless-mcp

需要配置的环境变量

EXPO_PROJECTAbsolute path of the Expo project to render (can also be passed per call as projectPath).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmexpo-headless-mcp0.2.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
entry	string	否	相对于项目的入口文件，例如 App.tsx
scale	number	否	PNG 像素缩放比例（默认值为 1.5）
width	number	否	屏幕宽度，单位为 dp（默认值为 390）
height	number	否	屏幕高度，单位为 dp（默认值为 844）
reload	boolean	否	重新打包并重启应用（默认值：true）
projectPath	string	否	Expo 项目目录（默认值：EXPO_PROJECT 环境变量或服务器当前工作目录）

详细介绍

expo-headless-mcp

一个 MCP 服务，让 AI 无需模拟器、手机或浏览器，即可查看和操作 Expo / React Native 应用——提供真实 PNG 截图、点击、输入、滚动和自动 Bug 排查。（俄语版：README.ru.md）

文档

快速入门 — 为 Claude Code / Claude Desktop / Cursor 安装并首次运行
工具参考 — 所有工具及其参数
设备模式 — Android 模拟器 / 手机和 iOS Simulator、授权与安全模型
工作原理 — 架构、支持内容和开发
故障排除

工作原理

Metro + Expo Go 需要原生运行时，因此这里采用不同方式：

esbuild 打包你的项目（App.* 或 main），将 react-native 替换为轻量 shim（src/shim/rn.js），并将仅支持原生的包（expo-*、react-native-*）替换为存根。
应用在 Node 中运行；React 会将内容渲染到我们自己的树（react-reconciler）中。
使用 Yoga（React Native 所用的 flexbox 引擎）计算布局，并通过 Skia（@napi-rs/canvas）绘制为 PNG。

限制：这只是近似模拟，并非真正的 iOS / Android——字体、阴影、动画和原生模块都有差异；不支持 expo-router / react-navigation；refresh_screen 会重置状态。

工具

refresh_screen — 重新构建并显示屏幕（projectPath、entry、width、height、scale、reload）
click_screen — 在 x,y 处点击，或通过 target（testID / 文本）、long 或 alert:<button> 点击
type_text — 在 TextInput 中输入（target 或 x,y、submit、append）
scroll_screen — 滚动 x,y 下方的区域
describe_screen — 输出元素文本大纲及布局警告（重叠、文本裁剪、超出屏幕）
auto_test — 对所有内容进行猴子测试：多轮重新加载，用不同数据填充每个输入框（空值、无效值、有效值、超长内容、特殊字符、西里尔文、CJK、阿拉伯文 / 希伯来文、emoji），点击每个按钮 / 开关（滚动以便触达），并关闭提示框。通过截图报告崩溃、控制台错误、布局问题和无响应按钮。

该服务内置 instructions：每次代码更改后，AI 都必须重新构建、手动检查、运行 auto_test、修复问题并重复，直到全部检查通过且无异常。MCP 提示词 verify_changes 会触发相同的循环。

语言

服务文本为英语，AI 会使用用户所用的语言回复。渲染时会回退到系统字体，以支持拉丁文、西里尔文、CJK、天城文、阿拉伯文、希伯来文和 emoji（在 Linux 上安装 Noto 字体）。不会模拟从右到左的布局（I18nManager）；RTL 文本本身可以正常渲染。

安装

claude mcp add expo -e EXPO_PROJECT=/path/to/app -- npx -y expo-headless-mcp

测试：npm test（端到端），node test/mcp.js（stdio）。

真实设备模式（可选）

除了无头渲染器，AI 还可以通过 adb（Windows、macOS、Linux）操控 Android 模拟器或通过 USB 连接的手机上的 Expo Go，也可以操控 已启动的 iOS Simulator（仅限安装了 Xcode 的 macOS）。不支持实体 iPhone：Apple 不允许在没有大量工具支持的情况下进行远程输入——请自行在 iPhone 上打开 Expo Go。

工具：device_list（只读）、use_target（device / headless）、press_key；先使用 refresh_screen、click_screen、type_text、scroll_screen、describe_screen 查看屏幕，再在设备上操作。

服务内置的安全规则：

没有连接设备 / 缺少 adb → 服务会说明情况，不会更改任何内容，并建议你自行检查应用（或使用无头模式）。
USB 调试已关闭或设备未获授权 → 服务会说明如何启用，并提前警告你，它会在手机上点击、输入和滚动。
先征得同意。 在操控实体手机之前、缺少 Expo Go 时安装之前，以及 Expo Go 的 SDK 与项目不匹配时替换 Expo Go 之前，服务都会先征求你的同意（通过 MCP elicitation；如果客户端不支持，则由 AI 在聊天中询问）。匹配的构建版本来自 Expo 的官方发布列表；需要先卸载才能降级，这一点会在问题中说明。如果你拒绝，服务不会执行任何操作，也不会再次尝试。
服务只会操作 Expo Go：每次点击、输入或滑动前，都会先检查 Expo Go 是否处于前台。允许的按键：返回、回车、Tab、删除。
auto_test 仅适用于无头模式（它会点击所有内容）。无法通过 adb 输入非 ASCII 文本——请在无头模式下测试其他语言。

**状态：**作者已在实体手机上使用 Android 路径，并通过针对伪造 adb 的自动化测试进行验证。

启动开发服务器会在你的项目中运行 npx expo start（如果缺少依赖项，会先询问是否运行 npm install）。可通过 EXPO_MCP_METRO_CMD 覆盖命令；将 EXPO_MCP_ADB 设置为使用特定的 adb。

iOS Simulator 说明

需要 macOS、Xcode（xcrun simctl）以及用于点击、输入和查看 UI 树的 Facebook idb（brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb）。如果没有 idb，服务只会告知你如何安装，绝不会自行安装。
只有在你同意后，才会安装或替换项目 SDK 对应的 Expo Go（使用 Expo 官方发布列表中的构建版本）。
模拟器是一次性的，因此无需检查每个应用的前台状态；iOS 没有硬件返回键。
**状态：**iOS 路径仅通过针对伪造 xcrun / idb 的测试进行验证——尚未在真实 Mac 上运行过。