@synnode/expo地铁mcp
MCP服务器，连接到正在运行的Expo/Metro开发服务器，并将其日志暴露给Claude Code。
使用 Chrome DevTools协议（CDP） Metro公开的检查器端点——与React Native DevTools使用的通道相同。与Expo SDK 50+兼容，包括新架构（无桥/JSI）。
安装
# Register with Claude Code CLI
claude mcp add expo-metro npx @synnode/expo-metro-mcp或者全局安装并注册：
npm install -g @synnode/expo-metro-mcp
claude mcp add expo-metro expo-metro-mcp添加服务器后重新启动Claude Code。
需求
- Expo/Metro开发服务器正在运行(
npx expo start) - 连接到Metro的设备或模拟器（应用程序必须正在运行才能显示日志）
配置
# Defaults — only override if needed
METRO_PORT=8081
METRO_HOST=localhost
LOG_BUFFER_SIZE=1000如果Metro在其他端口上运行：
claude mcp add expo-metro --env METRO_PORT=8082 npx @synnode/expo-metro-mcp可用工具
| 工具 | 说明 |
|---|---|
get_logs | 缓冲区中的最新日志。可选： lines, level (error/warn/info/log/debug), since （例如。 "30s", "2m"，unix时间戳） |
get_errors | 缓冲区堆栈跟踪错误。可选： lines |
get_status | 连接状态、设备名称和缓冲区统计信息 |
clear_logs | 清除日志缓冲区 |
watch_logs | 轮询时间窗口内的传入日志。可选： duration （例如。 "10s"，最大值 "30s"), level |
connect | 从Metro获取CDP连接。使用后 disconnect 或者当 get_status 显示已断开连接 |
disconnect | 释放CDP连接，以便React Native DevTools可以自由连接 |
reload | 通过Metro重新加载React Native应用程序 |
resolve_stack | 根据Metro源代码映射解析堆栈跟踪，显示原始文件/行而不是包偏移量 |
list_devices | 列出活动的iOS模拟器和Android模拟器 |
screenshot | 截取活动模拟器/仿真器的屏幕截图。返回图像+像素尺寸。可选： platform, device_id |
tap | 点击活动模拟器/仿真器上的x、y坐标。可选： platform, device_id |
swipe | 从一个坐标滑动到另一个坐标。可选： duration_ms, platform, device_id |
input_text | 在焦点输入字段中键入文本——无需屏幕键盘即可使用。可选： platform, device_id |
input_key | 发送一个特殊按键： enter, backspace, delete, tab, escape, back, space，箭头键。可选： platform, device_id |
evaluate | 通过Metro CDP在连接的应用运行时运行JavaScript。支持异步表达式。可用于读取状态、调用应用程序帮助程序、戳导航或更改调试状态。可选： timeout_ms |
mmkv_get | 从仅用于开发的MMKV调试挂钩中读取原始字符串值 globalThis.__EXPO_METRO_MCP__.mmkv |
mmkv_set | 通过MMKV调试挂钩写入原始字符串值 |
mmkv_remove | 通过MMKV调试挂钩删除密钥 |
mmkv_keys | 列出通过MMKV调试挂钩可用的所有密钥 |
mmkv_get_json | 读取并解析JSON值的MMKV条目 |
mmkv_set_json | 将任何JSON可序列化值存储在MMKV中，无需手动字符串化 |
mmkv_merge_json | 将对象浅合并到现有的JSON值MMKV条目中 |
zustand_persist_get | 读取持久的Zustand MMKV有效载荷并拆分 state 和 version |
zustand_persist_set | 在中写入持久的Zustand有效载荷 { state, version? } 形状 |
zustand_persist_merge | 将字段合并到现有的持久Zustand中 state 对象 |
运行时评估
evaluate 通过CDP直接在连接的React Native应用运行时运行JavaScript Runtime.evaluate.
它有什么好处：
- 检查全局、存储和导航状态
- 调用调试助手或导出函数
- 通过应用程序的JS运行时读取或写入应用程序持久性
- 调试期间切换功能标志或临时状态
- 在不重建UI自动化流程的情况下验证假设
笔记：
- 表达式会自动等待，因此
Promise结果开箱即用 - 返回值在可能的情况下被序列化；不可序列化的对象会回退到其运行时描述
- 这是一个锋利的工具。非常适合发展，被错误的人诅咒
MMKV调试挂钩
如果你的应用程序使用 react-native-mmkv，您可以公开一个仅限开发人员的小钩子，让MCP种子或检查持久状态，而无需手写eval代码段。
应用程序侧钩示例：
import {createMMKV} from "react-native-mmkv";
export const mmkv = createMMKV({
id: "synorga-app",
});
if (__DEV__) {
globalThis.__EXPO_METRO_MCP__ = {
...globalThis.__EXPO_METRO_MCP__,
mmkv: {
id: "synorga-app",
getItem: (key: string) => mmkv.getString(key) ?? null,
setItem: (key: string, value: string) => mmkv.set(key, value),
removeItem: (key: string) => mmkv.remove(key),
getAllKeys: () => mmkv.getAllKeys(),
},
};
}一旦暴露，MCP可以使用：
- 低级MMKV工具：
mmkv_get,mmkv_set,mmkv_remove,mmkv_keys - JSON助手：
mmkv_get_json,mmkv_set_json,mmkv_merge_json - 状态助手：
zustand_persist_get,zustand_persist_set,zustand_persist_merge
这有意保持通用性，因此它适用于持久的Zustand状态和普通的MMKV使用，而无需将MCP耦合到您的存储内部。
对于大多数人工智能驱动的状态播种，Zustand助手是最佳选择。他们每次都避免手工构建持久的包装形状。
屏幕截图和UI自动化
screenshot, tap, swipe, input_text，以及 input_key 直接与您的跑步模拟器或仿真器交互，无需额外的软件包或付费计划。
要求：
- iOS屏幕截图：安装了Xcode的macOS(
xcrun simctl必须可用） - iOS点击/滑动/输入:
idb--Facebook的iOS开发桥梁
brew tap facebook/fb && brew install idb-companion
pip3 install fb-idb- 安卓:
adb在您的PATH（Android SDK平台工具的一部分）中，所有工具都可以开箱即用
笔记：
screenshot返回图像及其像素尺寸——直接使用这些坐标tap/swipe，无需手动缩放input_text在不需要屏幕键盘出现的情况下，在焦点字段中键入- 填写表格：
tap领域→input_text价值→input_key "enter"提交 - 如果多个设备正在运行，请使用
list_devices找到ID并通过device_id - iOS屏幕截图无需idb即可使用——只需点击/滑动/输入即可
与React Native DevTools一起使用
CDP一次只允许一个客户端。MCP和DevTools之间的切换是无缝的——最后一个连接接管，另一个自动被踢出。
- 使用DevTools：只需打开或重新连接即可。MCP将自动断开连接。
- 返回MCP：呼叫
connectDevTools将失去连接。
disconnect 如果你想先显式释放连接，它是可用的，但这不是必需的。
get_status 始终显示MCP当前是否已连接。
运作原理
Metro在以下位置公开了CDP WebSocket /inspector/debug.On connect，服务器调用 /json/list 发现活动设备目标，然后通过CDP连接并启用 Runtime.consoleAPICalled 事件。Metro构建错误(build_failed, bundling_error)通过单独捕获 /events WebSocket，自动重新连接。
教授Claude代码关于此MCP
添加 SKILL.md 到您的项目根（或 CLAUDE.md)教Claude Code如何有效地使用此MCP——何时检查日志、如何调试错误、如何使用屏幕截图和点击等等。
curl -o SKILL.md https://raw.githubusercontent.com/Synnode/expo-metro-mcp/master/SKILL.md备注
- 如果启动时无法访问Metro：服务器正常启动，
get_status回报connected: false.致电connect一旦你的开发服务器启动。 - 记忆受到以下因素的限制
LOG_BUFFER_SIZE（循环缓冲区，最旧的条目先删除）。 - CDP连接可能会在Metro的终端中显示“不受支持的调试客户端”通知——这是无害的。