react-native-devtools-mcp

MCP server that gives AI agents eyes, hands, and X-ray vision into any React Native app running in an iOS simulator or Android emulator.

• Capture screenshots and screen recordings
• Inspect the full UI accessibility tree with element labels, types, and bounds
• Interact with the app: tap, type, scroll, press buttons, open deep links
• Capture device-level console logs (simctl/logcat) and JS-level console output (via Metro CDP)
• Execute arbitrary JavaScript inside the running app
• Check Metro bundler status and connected runtimes

Works with any MCP-compatible AI agent: OpenCode, Claude Code, Cursor, Windsurf, etc.

Prerequisites

• Node.js >= 20
• iOS: Xcode with Simulator, plus Facebook IDB for view hierarchy:

  brew tap facebook/fb && brew install idb-companion
  pip3 install fb-idb

• Android: Android SDK with adb on PATH and a configured emulator

Quick Start

1. Build

cd ~/react-native-devtools-mcp
npm install
npm run build

2. Boot a simulator or emulator

# iOS
xcrun simctl boot "iPhone 15 Pro"

# Android
emulator -avd <avd_name>

3. Configure your AI tool

OpenCode — add to ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "react-native": {
      "command": "node",
      "args": ["/absolute/path/to/react-native-devtools-mcp/dist/index.js"]
    }
  }
}

Claude Code:

claude mcp add react-native node /absolute/path/to/react-native-devtools-mcp/dist/index.js

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "react-native": {
      "command": "node",
      "args": ["/absolute/path/to/react-native-devtools-mcp/dist/index.js"]
    }
  }
}

Tools

Observation

Tool	Description	Params
screenshot	Capture screen as PNG image	name? (string)
get_view_hierarchy	Dump UI accessibility tree with labels, types, bounds	format? (raw|tree), filter? (string)
get_device_info	Device/simulator info and connection status	none
get_device_logs	Device-level console logs (simctl log / adb logcat)	duration? (seconds, default 30), filter? (regex)
get_metro_status	Metro bundler status and connected RN runtimes	none
get_js_logs	JS console output (console.log/warn/error) via Metro CDP	duration? (seconds, default 5), filter? (regex), level? (all|log|warn|error|info|debug)

Interaction

Tool	Description	Params
tap	Tap at screen coordinates	x (number), y (number)
type_text	Type into focused input field	text (string)
press_button	Press device button	button (home|back|enter|delete)
scroll	Scroll in a direction	direction (up|down|left|right), amount? (pixels, default 500)
open_deeplink	Open URL or deep link in app	url (string)
js_eval	Execute JavaScript in the running app via Metro CDP	expression (string)

Utility

Tool	Description	Params
ping	Health check — device status	none
start_recording	Start screen recording	name? (string)
stop_recording	Stop recording, return file path	none
help	List all tools with params and system status	none

Environment Variables

All optional. The server auto-detects everything.

Variable	Description	Default
RN_DEVTOOLS_PLATFORM	Force platform: ios or android	auto-detect
RN_DEVTOOLS_DEVICE_ID	Force device UDID (iOS) or serial (Android)	auto-detect
RN_DEVTOOLS_IDB_PATH	Path to idb binary for iOS view hierarchy	auto-discover
RN_DEVTOOLS_METRO_PORT	Metro bundler port	8081
RN_DEVTOOLS_METRO_HOST	Metro bundler host	127.0.0.1

Use as Library

react-native-devtools-mcp is designed to be extended. Import createServer to get a pre-configured MCP server with all generic tools, then register your own:

import { createServer } from "react-native-devtools-mcp";

const server = createServer({ name: "my-custom-mcp", version: "1.0.0" });

// Add your own tools on top of the 16 built-in ones
server.tool("my_tool", "Does something custom", {}, async () => {
  return { content: [{ type: "text", text: "result" }] };
});

Individual register functions are also exported if you want selective tool registration:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  registerScreenshotTool,
  registerViewHierarchyTool,
  registerInteractionTools,
} from "react-native-devtools-mcp";

const server = new McpServer({ name: "minimal", version: "1.0.0" });
registerScreenshotTool(server);
registerViewHierarchyTool(server);
registerInteractionTools(server);

Metro/CDP utilities are exported too: getMetroTargets, getMetroStatus, cdpEval, captureJsLogs, getMetroBaseUrl.

How it Works

No app code changes required. The server connects to existing debug interfaces:

• iOS Simulator: xcrun simctl for screenshots, input, logs, deep links. Facebook IDB (idb ui describe-all) for view hierarchy with accessibility labels, frames, and element roles.
• Android Emulator: adb for screenshots, input, logs, deep links. uiautomator dump for view hierarchy with resource-ids (testIDs), text, and bounds.
• Metro Bundler: Chrome DevTools Protocol (CDP) over WebSocket for JS console capture (Runtime.consoleAPICalled), JS evaluation (Runtime.evaluate), and runtime status. Connects to http://localhost:8081/json to discover available runtimes.

Troubleshooting

"No booted simulator or emulator detected" Boot a simulator (xcrun simctl boot "iPhone 15 Pro") or emulator (emulator -avd <name>), or set RN_DEVTOOLS_PLATFORM and RN_DEVTOOLS_DEVICE_ID env vars.

View hierarchy empty on iOS iOS view hierarchy requires Facebook IDB. Install it:

brew tap facebook/fb && brew install idb-companion
pip3 install fb-idb

Verify with: idb ui describe-all --udid <simulator-udid>. If idb is not on PATH, set RN_DEVTOOLS_IDB_PATH=/path/to/idb.

IDB not found The server searches common locations automatically. If it still can't find IDB, set RN_DEVTOOLS_IDB_PATH to the absolute path of the idb binary (e.g., ~/Library/Python/3.9/bin/idb).

Screenshot fails on Android Ensure adb is on PATH and the emulator is fully booted past the lock screen.

Metro/JS tools not working Ensure Metro bundler is running and accessible. Test with:

curl http://localhost:8081/json

If Metro runs on a different port, set RN_DEVTOOLS_METRO_PORT.

JS eval returns "No React Native runtime found" The app must be running and connected to Metro. Check get_metro_status to see connected runtimes.

License

MIT