Metro MCP

metro-mcp

一个基于插件的 MCP 服务，用于 React Native 运行时调试、检查和自动化。通过 Chrome DevTools Protocol 连接 Metro 打包器——大多数功能无需更改应用代码。

适用于 Expo、纯 React Native，以及任何使用 Metro + Hermes 的项目。

---

目录

• 快速开始
• 要求
• 工作原理
• 功能
• Chrome DevTools
• Claude Code 状态栏
• 测试录制
• 应用集成
• 配置
• 自定义插件
• 兼容性

---

快速开始

Claude Code

claude mcp add metro-mcp -- npx -y metro-mcp
# or with Bun
claude mcp add metro-mcp -- bunx metro-mcp

Codex

codex mcp add metro-mcp -- npx -y metro-mcp
# or with Bun
codex mcp add metro-mcp -- bunx metro-mcp

Codex 默认将 MCP 服务存储在 ~/.codex/config.toml 中，Codex CLI 和 IDE 扩展共用此配置。

如果你更喜欢手动配置：

[mcp_servers.metro-mcp]
command = "npx"
args = ["-y", "metro-mcp"]

OpenCode

运行 OpenCode 的交互式 MCP 安装程序：

opencode mcp add

选择本地服务，将其命名为 metro-mcp，并使用 npx -y metro-mcp 作为命令。

如果你更喜欢手动配置，可将以下内容添加到项目中的 opencode.json，或添加到 ~/.config/opencode/opencode.json 以进行全局安装：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "metro-mcp": {
      "type": "local",
      "command": ["npx", "-y", "metro-mcp"],
      "enabled": true
    }
  }
}

也可以使用 Bun：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "metro-mcp": {
      "type": "local",
      "command": ["bunx", "metro-mcp"],
      "enabled": true
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "metro-mcp": {
      "command": "npx",
      "args": ["-y", "metro-mcp"]
    }
  }
}

也可以使用 Bun：

{
  "mcpServers": {
    "metro-mcp": {
      "command": "bunx",
      "args": ["metro-mcp"]
    }
  }
}

在多个 Agent 中安装

如果你使用多个 MCP 客户端，add-mcp 可以为受支持的 Agent 写入配置，包括 Claude Code、Codex、Cursor、OpenCode 和 VS Code：

npx add-mcp metro-mcp --all -g -y

metro-mcp 支持同时连接多个 Agent。标准 stdio 安装会为同一项目目录及 Metro/配置选项启动或复用本地共享守护进程，因此 Codex、Claude Code、Cursor 和其他客户端可以同时连接到同一个正在运行的 Metro 应用，并查看相同的日志、网络请求、错误和运行时状态。

共享 HTTP 服务 / Supergateway

如果你想自行公开一个长期运行的 MCP 端点，可显式启动共享服务：

npx -y metro-mcp serve --mcp-port 8765

此服务通过 http://127.0.0.1:8765/mcp 提供 Streamable HTTP。该端点同时支持 2025 年版 MCP 握手和 2026-07-28 协商；/sse 和 /messages 则有意不提供。supergateway 等工具可以指向 Streamable HTTP 端点，而不是每次请求都启动新的 stdio 进程。

使用自定义 Metro 端口

codex mcp add metro-mcp -- npx -y metro-mcp --port 19000
# or
claude mcp add metro-mcp -- npx -y metro-mcp --port 19000

对于 OpenCode，将端口添加到命令数组中：

"command": ["npx", "-y", "metro-mcp", "--port", "19000"]

---

要求

• Node.js 18+ 或 Bun 1.0+
• iOS：Xcode 14+ 和 Simulator（大多数操作会使用 xcrun simctl）
• Android：Android SDK，且 adb 已加入 PATH
• IDB （可选）：部分 iOS 操作会回退到 IDB (idb-companion)——使用 brew install idb-companion 安装。需要 IDB 时，工具会提示你。

---

工作原理

metro-mcp 通过与 Chrome DevTools 相同的方式连接到正在运行的 Metro 开发服务器：

1. 通过扫描端口发现 Metro（8081、8082、19000–19002）
2. 通过 Chrome DevTools Protocol（CDP）连接到 Hermes
3. 将控制台日志、网络请求和错误流式传输到缓冲区
4. 将所有内容作为 MCP 工具、资源和提示词提供

核心调试功能无需修改应用。

---

功能

插件	工具数	描述
console	2	收集并筛选控制台日志
network	6	跟踪网络请求、检查响应正文并查看统计信息
errors	3	收集运行时异常 + 检测 Metro 捆绑错误
evaluate	1	在应用运行时中执行 JavaScript
device	4	设备管理、连接状态和应用重新加载
environment	4	检查构建标志、平台常量、环境变量和 Expo 配置
source	1	符号化堆栈跟踪
redux	3	检查 Redux 状态并分发操作
components	5	检查 React 组件树
storage	3	读取 AsyncStorage
simulator	6	控制 iOS 模拟器 / Android 设备
deeplink	2	跨平台深层链接测试
permissions	5	检查和管理 iOS 模拟器和 Android 模拟器上的应用权限
ui-interact	6	UI 自动化（点击、滑动、输入）
navigation	4	React Navigation / Expo Router 状态
accessibility	3	无障碍审计
commands	2	自定义应用命令
automation	3	用于等待 / 轮询异步状态变化的辅助工具
profiler	9	CPU 性能分析（React DevTools hook）+ 堆采样 + 渲染跟踪
test-recorder	7	录制交互并生成 Appium、Maestro 或 Detox 测试
filesystem	5	浏览并读取应用沙盒目录中的文件（Documents、缓存、SQLite 数据库）
devtools	1	通过 CDP 代理打开 Chrome DevTools，并与 MCP 同时运行
debug-globals	1	自动发现 Redux store、Apollo Client 和其他调试全局对象
inspect-point	1	基于坐标检查 React 组件（实验性）
statusline	1	集成 Claude Code 状态栏

→ 查看完整工具参考。

---

Chrome DevTools

Hermes（React Native JavaScript 引擎）一次只允许建立 一个 CDP 调试器连接。由于 metro-mcp 使用该连接，在 Metro 中按下“j” 或点击开发菜单中的 “Open Debugger” 会抢占连接并断开 MCP。

metro-mcp 通过内置的 CDP 代理解决此问题。该代理会复用唯一的 Hermes 连接，让 Chrome DevTools 与 MCP 同时运行。

打开 DevTools

请使用 open_devtools MCP 工具，而不要使用常规方法。它会打开与 Metro 使用的相同 React Native DevTools 前端（rn_fusebox），但会通过代理路由 WebSocket 连接，从而让两者共存。

该工具会使用与 Metro 相同的检测方式自动查找 Chrome 或 Edge，并打开一个独立的 DevTools 窗口。

应避免的操作

方法	结果
在 Metro 终端中按 "j"	断开 MCP
在开发菜单中选择 "Open Debugger"	断开 MCP
open_devtools MCP 工具	可与 MCP 一起使用

配置

CDP 代理默认已启用。要更改端口或禁用它：

# Set a fixed proxy port
METRO_MCP_PROXY_PORT=9222 npx metro-mcp

# Disable the proxy entirely
METRO_MCP_PROXY_ENABLED=false npx metro-mcp

---

Claude Code 状态栏

在 Claude Code 状态栏中查看实时 Metro CDP 连接状态。

在 Claude Code 中运行 setup_statusline — 它会将脚本写入 ~/.claude/metro-mcp-statusline.sh，然后让 Claude 将其添加到状态栏：

/statusline add the script at ~/.claude/metro-mcp-statusline.sh

状态栏片段显示三种状态：

状态	显示
未运行	Metro ○（变暗）
正在运行，未连接	Metro ●（红色）
已连接	Metro ● localhost:8081（绿色）

---

测试录制

录制真实用户交互（点击、文本输入、滚动），并生成可用于生产环境的测试 — 无需更改应用代码。

AI 驱动的测试生成

描述一个流程，AI 会导航应用，然后生成测试：

"为访客结账流程编写一个 Appium 测试 — 从欢迎屏幕点击“开始购物”开始，并在购物车屏幕可见时结束。"

AI 会调用 start_test_recording，使用 tap_element/type_text/swipe 进行导航，然后根据从 fiber 树中观察到的真实选择器生成完整测试。

手动录制

start_test_recording   → inject interceptors
(interact with the app)
stop_test_recording    → retrieve event log
generate_test_from_recording format=appium

支持 Appium (WebdriverIO)、Maestro YAML 和 Detox。

→ 完整详情、格式示例和提示请参阅测试指南。

---

应用集成（可选）

注册自定义命令并向 MCP 服务公开状态 — 无需安装软件包。在开发模式下，将以下内容添加到应用入口点：

if (__DEV__) {
  globalThis.__METRO_BRIDGE__ = {
    commands: {
      // Run custom actions from the MCP client
      login: async ({ email, password }) => {
        return await authService.login(email, password);
      },
      resetOnboarding: () => {
        AsyncStorage.removeItem('onboarding_completed');
      },
      switchUser: ({ userId }) => {
        store.dispatch(switchUser(userId));
      },
    },
    state: {
      // Expose state snapshots readable via get_redux_state
      userStore: () => useUserStore.getState(),
    },
  };
}

使用 list_commands 和 run_command 从 MCP 客户端调用这些命令。

如需实时 Redux 操作跟踪、导航事件、性能标记和 React 渲染分析等增强功能，请安装 metro-bridge — 请参阅客户端 SDK 文档和性能分析指南。

---

配置

有关环境变量、CLI 参数和配置文件选项，请参阅配置文档。

---

自定义插件

metro-mcp 完全可扩展。请参阅插件指南，了解如何构建自己的工具和资源。

---

兼容性

• React Native：0.70+
• Expo：SDK 49+
• 运行时：Node.js 18+ 或 Bun 1.0+
• 平台：iOS 模拟器、Android 模拟器、通过 USB 连接的实体设备

许可证

MIT