Getting Started

metro-mcp is a plugin-based MCP server for React Native runtime debugging, inspection, and automation. It connects to Metro bundler via Chrome DevTools Protocol — no app code changes needed for most features.

Works with Expo, bare React Native, and any project using Metro + Hermes.

Requirements

• Node.js 18+ or Bun 1.0+
• iOS: Xcode 14+ with Simulator (xcrun simctl is used for most operations)
• Android: Android SDK with adb on your PATH
• IDB (optional): Some iOS operations fall back to IDB (idb-companion) — install with brew install idb-companion. Tools will tell you when IDB is needed.

Installation

Claude Code

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

Cursor / VS Code

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

Or use the one-click install buttons:

With a custom Metro port

claude mcp add metro-mcp -- npx -y metro-mcp --port 19000

How It Works

metro-mcp connects to your running Metro dev server the same way Chrome DevTools does:

1. Discovers Metro via port scanning (8081, 8082, 19000–19002)
2. Connects to Hermes via Chrome DevTools Protocol (CDP)
3. Streams console logs, network requests, and errors into buffers
4. Exposes everything as MCP tools, resources, and prompts

No app modifications required for core debugging features.

Compatibility

	Supported
React Native	0.70+ (Hermes required)
Expo	SDK 49+
Node.js	18+
Bun	1.0+
Platforms	iOS Simulator, Android Emulator, physical devices via USB

Chrome DevTools

Hermes only allows a single CDP connection at a time. metro-mcp solves this with a built-in CDP proxy that multiplexes the connection, letting Chrome DevTools and the MCP coexist.

Use the open_devtools MCP tool instead of pressing "j" in Metro or tapping "Open Debugger" in the dev menu — those will steal the connection and disconnect the MCP.

The proxy is enabled by default. To configure it:

# Fixed proxy port
METRO_MCP_PROXY_PORT=9222 npx metro-mcp

# Disable the proxy
METRO_MCP_PROXY_ENABLED=false npx metro-mcp

Claude Code Status Bar

Get live Metro connection status in your Claude Code status bar.

Run setup_statusline in Claude Code — it writes a script to ~/.claude/metro-mcp-statusline.sh, then:

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

State	Display
Not running	Metro ○ (dimmed)
Running, not connected	Metro ● (red)
Connected	Metro ● localhost:8081 (green)

Next Steps

• Configuration — environment variables, CLI args, config file
• App Integration (SDK) — optional SDK for enhanced features
• Tools Reference — all available MCP tools
• Custom Plugins — extend metro-mcp with your own tools