Skip to content
Back to search

metro-mcp

πŸš‡ A plugin-based MCP server for React Native runtime debugging, inspection, and automation. Connects to Metro bundler via Chrome DevTools Protocol β€” no app code changes needed for most features.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/steve228uk--metro-mcp/badge.svg)](/listings/steve228uk--metro-mcp)

HTML

<a href="/listings/steve228uk--metro-mcp"><img src="/api/listings/steve228uk--metro-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 stores MCP servers in `~/.codex/config.toml` by default, and the Codex CLI and IDE extension share that configuration.

If you prefer to configure it manually:

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

OpenCode

Run OpenCode's interactive MCP installer:

opencode mcp add

Choose a local server, name it `metro-mcp`, and use `npx -y metro-mcp` as the command.

If you prefer to configure it manually, add this to `opencode.json` in your project, or to `~/.config/opencode/opencode.json` for a global install:

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

Or with 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"]
    }
  }
}

Or with Bun:

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

Install across multiple agents

If you use several MCP clients, [`add-mcp`](https://github.com/neondatabase/add-mcp) can write the config for supported agents, including Claude Code, Codex, Cursor, OpenCode, and VS Code:

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

metro-mcp supports multiple agents at the same time. Standard stdio installs start or reuse a local shared daemon for the same project directory and Metro/config options, so Codex, Claude Code, Cursor, and other clients can connect concurrently to the same running Metro app and see the same logs, network requests, errors, and runtime state.

Shared HTTP server / Supergateway

If you want to expose one long-lived MCP endpoint yourself, start the shared server explicitly:

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

This serves Streamable HTTP at `http://127.0.0.1:8765/mcp`. The endpoint supports both the 2025-era MCP handshake and the 2026-07-28 negotiation; `/sse` and `/messages` are intentionally unavailable. Tools such as [`supergateway`](https://github.com/supercorp-ai/supergateway) can point at the Streamable HTTP endpoint instead of launching a fresh stdio process per request.

With custom Metro port

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

For OpenCode, add the port to the command array:

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 349 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # metro-mcp
  2. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=metro-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22metro-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)
  3. [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=metro-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1ldHJvLW1jcCJdLCJlbnYiOnt9fQ==)
  4. A plugin-based MCP server for React Native runtime debugging, inspection, and automation. Connects to Metro bundler via Chrome DevTools Protocol β€” **no app code changes needed** for most features.
  5. Works with **Expo**, **bare React Native**, and any project using **Metro + Hermes**.
  6. ---
  7. ## Contents
  8. - [Quick Start](#quick-start)
  9. - [Requirements](#requirements)
  10. - [How It Works](#how-it-works)
  11. - [Features](#features)
  12. - [Chrome DevTools](#chrome-devtools)
  13. - [Claude Code Status Bar](#claude-code-status-bar)
  14. - [Test Recording](#test-recording)
  15. - [App Integration](#app-integration-optional)
  16. - [Configuration](#configuration)
  17. - [Custom Plugins](#custom-plugins)
  18. - [Compatibility](#compatibility)
  19. ---
  20. ## Quick Start
  21. ### Claude Code
  22. ```bash
  23. claude mcp add metro-mcp -- npx -y metro-mcp
  24. # or with Bun
  25. claude mcp add metro-mcp -- bunx metro-mcp
  26. ```
  27. ### Codex
  28. ```bash
  29. codex mcp add metro-mcp -- npx -y metro-mcp
  30. # or with Bun
  31. codex mcp add metro-mcp -- bunx metro-mcp
  32. ```
  33. Codex stores MCP servers in `~/.codex/config.toml` by default, and the Codex CLI and IDE extension share that configuration.
  34. If you prefer to configure it manually:
  35. ```toml
  36. [mcp_servers.metro-mcp]
  37. command = "npx"
  38. args = ["-y", "metro-mcp"]
  39. ```
  40. ### OpenCode
  41. Run OpenCode's interactive MCP installer:
  42. ```bash
  43. opencode mcp add
  44. ```
  45. Choose a local server, name it `metro-mcp`, and use `npx -y metro-mcp` as the command.
  46. If you prefer to configure it manually, add this to `opencode.json` in your project, or to `~/.config/opencode/opencode.json` for a global install:
  47. ```json
  48. {
  49. "$schema": "https://opencode.ai/config.json",
  50. "mcp": {
  51. "metro-mcp": {
  52. "type": "local",
  53. "command": ["npx", "-y", "metro-mcp"],
  54. "enabled": true
  55. }
  56. }
  57. }
  58. ```
  59. Or with Bun:
  60. ```json
  61. {
  62. "$schema": "https://opencode.ai/config.json",
  63. "mcp": {
  64. "metro-mcp": {
  65. "type": "local",
  66. "command": ["bunx", "metro-mcp"],
  67. "enabled": true
  68. }
  69. }
  70. }
  71. ```
  72. ### Cursor / VS Code
  73. ```json
  74. {
  75. "mcpServers": {
  76. "metro-mcp": {
  77. "command": "npx",
  78. "args": ["-y", "metro-mcp"]
  79. }
  80. }
  81. }
  82. ```
  83. Or with Bun:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "metro-mcp": {
  88. "command": "bunx",
  89. "args": ["metro-mcp"]
  90. }
  91. }
  92. }
  93. ```
  94. ### Install across multiple agents
  95. If you use several MCP clients, [`add-mcp`](https://github.com/neondatabase/add-mcp) can write the config for supported agents, including Claude Code, Codex, Cursor, OpenCode, and VS Code:
  96. ```bash
  97. npx add-mcp metro-mcp --all -g -y
  98. ```
  99. metro-mcp supports multiple agents at the same time. Standard stdio installs start or reuse a local shared daemon for the same project directory and Metro/config options, so Codex, Claude Code, Cursor, and other clients can connect concurrently to the same running Metro app and see the same logs, network requests, errors, and runtime state.
  100. ### Shared HTTP server / Supergateway
  101. If you want to expose one long-lived MCP endpoint yourself, start the shared server explicitly:
  102. ```bash
  103. npx -y metro-mcp serve --mcp-port 8765
  104. ```
  105. This serves Streamable HTTP at `http://127.0.0.1:8765/mcp`. The endpoint supports both the 2025-era MCP handshake and the 2026-07-28 negotiation; `/sse` and `/messages` are intentionally unavailable. Tools such as [`supergateway`](https://github.com/supercorp-ai/supergateway) can point at the Streamable HTTP endpoint instead of launching a fresh stdio process per request.
  106. ### With custom Metro port
  107. ```bash
  108. codex mcp add metro-mcp -- npx -y metro-mcp --port 19000
  109. # or
  110. claude mcp add metro-mcp -- npx -y metro-mcp --port 19000
  111. ```
  112. For OpenCode, add the port to the command array:
  113. ```json
  114. "command": ["npx", "-y", "metro-mcp", "--port", "19000"]
  115. ```
  116. ---
  117. ## Requirements
  118. - **Node.js** 18+ or **Bun** 1.0+
  119. - **iOS**: Xcode 14+ with Simulator (`xcrun simctl` is used for most operations)
  120. - **Android**: Android SDK with `adb` on your PATH
  121. - **IDB** _(optional)_: Some iOS operations fall back to [IDB (idb-companion)](https://github.com/facebook/idb) β€” install with `brew install idb-companion`. Tools will tell you when IDB is needed.
  122. ---
  123. ## How It Works
  124. metro-mcp connects to your running Metro dev server the same way Chrome DevTools does:
  125. 1. Discovers Metro via port scanning (8081, 8082, 19000–19002)
  126. 2. Connects to Hermes via Chrome DevTools Protocol (CDP)
  127. 3. Streams console logs, network requests, and errors into buffers
  128. 4. Exposes everything as MCP tools, resources, and prompts
  129. **No app modifications required** for core debugging features.
  130. ---
  131. ## Features
  132. | Plugin | Tools | Description |
  133. | ----------------- | ----- | -------------------------------------------------------------------------------- |
  134. | **console** | 2 | Console log collection with filtering |
  135. | **network** | 6 | Network request tracking, response body inspection, and stats |
  136. | **errors** | 3 | Runtime exception collection + Metro bundle error detection |
  137. | **evaluate** | 1 | Execute JavaScript in the app runtime |
  138. | **device** | 4 | Device management, connection status, and app reload |
  139. | **environment** | 4 | Build flags, platform constants, env vars, and Expo config inspection |
  140. | **source** | 1 | Stack trace symbolication |
  141. | **redux** | 3 | Redux state inspection and action dispatch |
  142. | **components** | 5 | React component tree inspection |
  143. | **storage** | 3 | AsyncStorage reading |
  144. | **simulator** | 6 | iOS simulator / Android device control |
  145. | **deeplink** | 2 | Cross-platform deep link testing |
  146. | **permissions** | 5 | Inspect and manage app permissions on iOS Simulator and Android Emulator |
  147. | **ui-interact** | 6 | UI automation (tap, swipe, type) |
  148. | **navigation** | 4 | React Navigation / Expo Router state |
  149. | **accessibility** | 3 | Accessibility auditing |
  150. | **commands** | 2 | Custom app commands |
  151. | **automation** | 3 | Wait/polling helpers for async state changes |
  152. | **profiler** | 9 | CPU profiling (React DevTools hook) + heap sampling + render tracking |
  153. | **test-recorder** | 7 | Record interactions and generate Appium, Maestro, or Detox tests |
  154. | **filesystem** | 5 | Browse and read files in app sandbox directories (Documents, caches, SQLite DBs) |
  155. | **devtools** | 1 | Open Chrome DevTools alongside the MCP via CDP proxy |
  156. | **debug-globals** | 1 | Auto-discover Redux stores, Apollo Client, and other debug globals |
  157. | **inspect-point** | 1 | Coordinate-based React component inspection (experimental) |
  158. | **statusline** | 1 | Claude Code status bar integration |
  159. β†’ See the [full tools reference](docs/tools.md).
  160. ---
  161. ## Chrome DevTools
  162. Hermes (the React Native JavaScript engine) only allows a **single CDP debugger connection** at a time. Since metro-mcp uses that connection, pressing **"j" in Metro** or tapping **"Open Debugger"** in the dev menu will steal the connection and disconnect the MCP.
  163. metro-mcp solves this with a built-in **CDP proxy** that multiplexes the single Hermes connection, allowing Chrome DevTools and the MCP to work simultaneously.
  164. ### Opening DevTools
  165. Use the `open_devtools` MCP tool instead of the usual methods. It opens the same React Native DevTools frontend (rn_fusebox) that Metro uses, but routes the WebSocket connection through the proxy so both can coexist.
  166. The tool automatically finds Chrome or Edge using the same detection as Metro and opens a standalone DevTools window.
  167. ### What to avoid
  168. | Method | What happens |
  169. | ----------------------------------- | ----------------------- |
  170. | Pressing **"j"** in Metro terminal | Disconnects the MCP |
  171. | **"Open Debugger"** in the dev menu | Disconnects the MCP |
  172. | `open_devtools` MCP tool | Works alongside the MCP |
  173. ### Configuration
  174. The CDP proxy is enabled by default. To change the port or disable it:
  175. ```bash
  176. # Set a fixed proxy port
  177. METRO_MCP_PROXY_PORT=9222 npx metro-mcp
  178. # Disable the proxy entirely
  179. METRO_MCP_PROXY_ENABLED=false npx metro-mcp
  180. ```
  181. ---
  182. ## Claude Code Status Bar
  183. Get live Metro CDP connection status in your Claude Code status bar.
  184. Run `setup_statusline` in Claude Code β€” it writes a script to `~/.claude/metro-mcp-statusline.sh`, then ask Claude to add it to your status bar:
  185. ```
  186. /statusline add the script at ~/.claude/metro-mcp-statusline.sh
  187. ```
  188. The status bar segment shows three states:
  189. | State | Display |
  190. | ---------------------- | -------------------------------- |
  191. | Not running | `Metro β—‹` (dimmed) |
  192. | Running, not connected | `Metro ●` (red) |
  193. | Connected | `Metro ● localhost:8081` (green) |
  194. ---
  195. ## Test Recording
  196. Record real user interactions (taps, text entry, scrolls) and generate production-ready tests β€” no app code changes required.
  197. ### AI-driven test generation
  198. Describe a flow and the AI navigates the app, then generates the test:
  199. > _"Write an Appium test for the guest checkout flow β€” start by tapping 'Start Shopping' on the welcome screen and end when the cart screen is visible."_
  200. The AI calls `start_test_recording`, navigates using `tap_element`/`type_text`/`swipe`, then generates a complete test with real selectors observed from the fiber tree.
  201. ### Manual recording
  202. ```
  203. start_test_recording β†’ inject interceptors
  204. (interact with the app)
  205. stop_test_recording β†’ retrieve event log
  206. generate_test_from_recording format=appium
  207. ```
  208. Supports **Appium (WebdriverIO)**, **Maestro YAML**, and **Detox**.
  209. β†’ See the [testing guide](docs/testing.md) for full details, format examples, and tips.
  210. ---
  211. ## App Integration (Optional)
  212. Register custom commands and expose state to the MCP server β€” no package needed. Add this to your app entry point in dev mode:
  213. ```typescript
  214. if (__DEV__) {
  215. globalThis.__METRO_BRIDGE__ = {
  216. commands: {
  217. // Run custom actions from the MCP client
  218. login: async ({ email, password }) => {
  219. return await authService.login(email, password);
  220. },
  221. resetOnboarding: () => {
  222. AsyncStorage.removeItem('onboarding_completed');
  223. },
  224. switchUser: ({ userId }) => {
  225. store.dispatch(switchUser(userId));
  226. },
  227. },
  228. state: {
  229. // Expose state snapshots readable via get_redux_state
  230. userStore: () => useUserStore.getState(),
  231. },
  232. };
  233. }
  234. ```
  235. Use `list_commands` and `run_command` to call these from the MCP client.
  236. For enhanced features like real-time Redux action tracking, navigation events, performance marks, and React render profiling, install [`metro-bridge`](https://www.npmjs.com/package/metro-bridge) β€” see the [client SDK docs](docs/sdk.md) and [profiling guide](docs/profiling.md).
  237. ---
  238. ## Configuration
  239. See [configuration docs](docs/configuration.md) for environment variables, CLI arguments, and config file options.
  240. ---
  241. ## Custom Plugins
  242. metro-mcp is fully extensible. See the [plugins guide](docs/plugins.md) to build your own tools and resources.
  243. ---
  244. ## Compatibility
  245. - **React Native**: 0.70+ (Hermes required)
  246. - **Expo**: SDK 49+
  247. - **Runtime**: Node.js 18+ or Bun 1.0+
  248. - **Platforms**: iOS Simulator, Android Emulator, physical devices via USB
  249. ## License
  250. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.