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

Cursor / VS Code

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

Or with Bun:

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

With custom Metro port

claude mcp add metro-mcp -- 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

| Plugin | Tools | Description | |--------|-------|-------------| | console | 2 | Console log collection with filtering | | network | 6 | Network request tracking, response body inspection, and stats | | errors | 3 | Runtime exception collection + Metro bundle error detection | | evaluate | 1 | Execute JavaScript in the app runtime | | device | 4 | Device management, connection status, and app reload | | source | 1 | Stack trace symbolication | | redux | 3 | Redux state inspection and action dispatch | | components | 5 | React component tree inspection | | storage | 3 | AsyncStorage reading | | simulator | 6 | iOS simulator / Android device control | | deeplink | 2 | Cross-platform deep link testing | | ui-interact | 6 | UI automation (tap, swipe, type) | | navigation | 4 | React Navigation / Expo Router state | | accessibility | 3 | Accessibility auditing | | commands | 2 | Custom app commands | | automation | 3 | Wait/polling helpers for async state changes | | profiler | 9 | CPU profiling (React DevTools hook) + heap sampling + render tracking | | test-recorder | 7 | Record interactions and generate Appium, Maestro, or Detox tests | | devtools | 1 | Open Chrome DevTools alongside the MCP via CDP proxy | | debug-globals | 1 | Auto-discover Redux stores, Apollo Client, and other debug global

... View full README on GitHub