metro-mcp

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.

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

---

Contents

• Quick Start
• Requirements
• How It Works
• Features
• Chrome DevTools
• Claude Code Status Bar
• Test Recording
• App Integration
• Configuration
• Custom Plugins
• Compatibility

---

Quick Start

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 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 and legacy SSE at http://127.0.0.1:8765/sse. Tools such as 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"]

---

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.

---

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.

---

Features