About
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.
Requirements
- Node.js 18+ or Bun 1.0+
- iOS: Xcode 14+ with Simulator (
xcrun simctlis used for most operations) - Android: Android SDK with
adbon 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:
- Discovers Metro via port scanning (8081, 8082, 19000–19002)
- Connects to Hermes via Chrome DevTools Protocol (CDP)
- Streams console logs, network requests, and errors into buffers
- 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 |
| environment | 4 | Build flags, platform constants, env vars, and Expo config inspection |
| 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 |
| permissions | 5 | Inspect and manage app permissions on iOS Simulator and Android Emulator |
| 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 |
| filesystem | 5 | Browse and read files in app sandbox directories (Documents, caches, SQLite DBs) |
| devtools | 1 | Open Chrome DevTools alongside the MCP via CDP proxy |
| debug-globals | 1 | Auto-discover Redux stores, Apollo Client, and other debug globals |
| inspect-point | 1 | Coordinate-based React component inspection (experimental) |
| statusline | 1 | Claude Code status bar integration |
→ See the full tools reference.
Chrome DevTools
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.
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.
Opening DevTools
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.
The tool automatically finds Chrome or Edge using the same detection as Metro and opens a standalone DevTools window.
What to avoid
| Method | What happens |
|---|---|
| Pressing "j" in Metro terminal | Disconnects the MCP |
| "Open Debugger" in the dev menu | Disconnects the MCP |
open_devtools MCP tool | Works alongside the MCP |