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
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
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:
- 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