React Native AI DevTools

React Native AI DevTools

An MCP server that gives AI assistants real-time access to a running React Native app. It bridges the gap between static code and live runtime, turning AI assistants from guessing machines into informed development partners.

Positioning: This is not a debugger. This is not a QA tool. This is a Runtime AI Bridge — the missing layer between AI coding assistants and live mobile applications. Without it, your AI assistant is blind. With it, the AI sees everything happening in your app in real time.

Features

Runtime Interaction

• Console Log Capture - Capture console.log, warn, error, info, debug with filtering and search
• React Component Inspection - Inspect component tree, props, state/hooks, and layout styles at runtime
• Network Request Tracking - Monitor HTTP requests/responses with headers, timing, and body content
• JavaScript Execution - Run code directly in your app (REPL-style) and inspect results
• Global State Debugging - Discover and inspect Apollo Client, Redux stores, Expo Router, and custom globals
• Bundle Error Detection - Get Metro bundler errors and compilation issues with file locations
• Debug Web Dashboard - Browser-based UI for real-time log and network monitoring

Device Control

• iOS Simulator - Screenshots, app management, URL handling, boot/terminate (via simctl)
• Android Devices - Screenshots, app install/launch, package management (via ADB)
• Unified Tap - Single tap tool with automatic fallback chain: fiber tree → accessibility → OCR → coordinates. Auto-detects platform, accepts pixels from screenshots
• UI Automation - Swipe, long press, text input, and key events on both platforms
• Accessibility Inspection - Query UI hierarchy to find elements by text, label, or resource ID
• OCR Text Extraction - Extract visible text with tap-ready coordinates (works on any screen content)

Under the Hood

• Auto-Discovery - Scans Metro on ports 8081, 8082, 19000-19002 automatically
• Smart Device Selection - Prioritizes Bridgeless > Hermes > standard React Native targets
• Auto-Reconnection - Exponential backoff (up to 8 attempts) when connection drops
• Efficient Buffering - Circular buffers: 500 logs, 200 network requests
• Platform Support - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)

Claude Code Skills

This repository includes pre-built Claude Code skills for common React Native debugging workflows. Skills let Claude handle multi-step tasks (session setup, log inspection, network debugging, etc.) with a single slash command instead of manual back-and-forth.

Available Skills

See skills/overview.md for a decision guide on which skill to use and a recommended workflow.

Installing Skills (Claude Code)

Copy the skill files into your project's .claude/skills/ directory:

# Install all skills
mkdir -p .claude/skills
curl -s https://api.github.com/repos/igorzheludkov/react-native-ai-devtools/contents/skills \
  | grep download_url \
  | cut -d '"' -f 4 \
  | xargs -I {} sh -c 'curl -sL {} -o .claude/skills/$(basename {})'

Or pick individual skills from the skills/ folder and drop them into .claude/skills/.

Then invoke in Claude Code:

/session-setup
/debug-logs
/network-inspect

Skills can also be triggered automatically — each skill file contains a "When to Trigger" section that tells Claude when to proactively invoke it without a slash command. For example, Claude will run bundle-check on its own when it detects a red screen, or session-setup when starting a fresh debugging task with no connection established yet.

Requirements

• Node.js 18+
• React Native app running with Metro bundler
• Optional for iOS UI automation: Facebook IDB - brew install idb-companion
• Optional for OCR: Python 3.6+ (EasyOCR is installed automatically, see OCR Setup)

Claude Code Setup

No installation required - Claude Code uses npx to run the latest version automatically.

Global (all projects)

claude mcp add rn-debugger --scope user -- npx react-native-ai-devtools

Project-specific

claude mcp add rn-debugger --scope project -- npx react-native-ai-devtools

Manual Configuration

Add to ~/.claude.json (user scope) or .mcp.json (project scope):

{
    "mcpServers": {
        "rn-debugger": {
            "type": "stdio",
            "command": "npx",
            "args": ["react-native-ai-devtools"]
        }
    }
}

Restart Claude Code after adding the configuration.

VS Code Copilot Setup

Requires VS Code 1.102+ with Copilot (docs).

Via Command Palette: Cmd+Shift+P → "MCP: Add Server"

Manual config - add to .vscode/mcp.json:

{
    "servers": {
        "rn-debugger": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "react-native-ai-devtools"]
        }
    }
}

Cursor Setup

Docs

Via Command Palette: Cmd+Shift+P → "View: Open MCP Settings"

Manual config - add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
    "mcpServers": {
        "rn-debugger": {
            "command": "npx",
            "args": ["-y", "react-native-ai-devtools"]
        }
    }
}

Available Tools

Usage Guide

The server also sends instructions on connection, so MCP clients automatically learn about get_usage_guide.

Connection & Logs

Network Tracking

App Inspection & Execution

Bundle Tools

React Component Inspection

Recommended Workflow: Use get_component_tree(focusedOnly=true, structureOnly=true) for a token-efficient overview of just the active screen (~1-3KB), then drill down with inspect_component or find_components.

Element Inspector (Coordinate-Based)

Inspect React components at specific screen coordinates - like React Native's built-in Element Inspector, but programmatically.

Quick Inspection (Recommended):

# Single call - auto-enables inspector, taps, returns component info
get_inspector_selection(x=210, y=400)

Returns:

Element: FastImageView
Path: App > RootNavigation > ... > PlayerModal > FastImage > FastImageView
Frame: (62.3, 130.0) 295.67x295.67
Style: { borderRadius: 15, overflow: "hidden" }

Manual Flow (for more control):

# 1. Enable the inspector overlay
toggle_element_inspector()

# 2. Tap to select element
tap with x=630 y=1200    # pixel coordinates from screenshot

# 3. Read the selection
get_inspector_selection()

# 4. Disable overlay when done
toggle_element_inspector()

Token Efficiency: Returns ~0.2-0.5KB vs 15-25KB for full component tree. Works on all React Native versions including Fabric/New Architecture.

UI Interaction (Cross-Platform)

Examples:

tap with text="Submit"                    # Finds and taps by visible text
tap with testID="login-btn"               # Finds by testID prop
tap with component="HamburgerIcon"        # Finds by React component name
tap with x=300 y=600                      # Taps at pixel coordinates (auto-converts)
tap with text="Menu" strategy="ocr"       # Forces OCR strategy only

Android (ADB)

iOS (Simulator)

Usage

1. Start your React Native app:

   npm start
   # or
   expo start
   

2. In Claude Code, scan for Metro:

   Use scan_metro to find and connect to Metro
   

3. Get logs:

   Use get_logs to see recent console output
   

get_logs Tool Reference

The get_logs tool has multiple parameters for controlling output size and format. Here's the complete reference:

Recommended Usage Patterns

# Quick overview (always start here)
get_logs with summary=true

# Recent errors only
get_logs with level="error" maxLogs=20

# Logs since last app reload
get_logs with startFromText="Running app" maxLogs=100

# Full messages for debugging specific issues
get_logs with maxLogs=10 verbose=true

# Token-efficient format for large outputs
get_logs with format="tonl" maxLogs=100

# Compact overview with shorter messages
get_logs with maxMessageLength=200 maxLogs=50

Filtering Logs

get_logs with maxLogs=20 and level="error"

Available levels: all, log, warn, error, info, debug

Start from Specific Line

get_logs with startFromText="iOS Bundled" and maxLogs=100

This finds the last (most recent) line containing the text and returns logs from that point forward. Useful for getting logs since the last app reload.

Search Logs

search_logs with text="error" and maxResults=20

Case-insensitive search across all log messages.

Token-Optimized Output

The tools include several options to reduce token usage when working with AI assistants.

Summary Mode (Recommended First Step)

Always start with summary=true - it gives you the full picture in ~10-20 tokens instead of potentially thousands:

get_logs with summary=true

Returns:

• Total count - How many logs are in the buffer
• Breakdown by level - See if there are errors/warnings at a glance
• Last 5 messages - Most recent activity (truncated to 100 chars each)

Example output:

Total: 847 logs

By Level:
  LOG: 612
  WARN: 180
  ERROR: 55

Last 5 messages:
  14:32:45 [LOG] User clicked button...
  14:32:46 [WARN] Slow query detected...
  14:32:47 [ERROR] Network request failed...

Why Summary First?

Recommended workflow:

1. summary=true → See the big picture
2. level="error" or level="warn" → Focus on problems
3. startFromText="..." → Get logs since specific event
4. verbose=true with low maxLogs → Full details when needed

Message Truncation

Long log messages are truncated by default (500 chars). Adjust as needed:

# Shorter for overview
get_logs with maxMessageLength=200

# Full messages (use with lower maxLogs)
get_logs with maxLogs=10 verbose=true

# Unlimited
get_logs with maxMessageLength=0

TONL Format

Use TONL (Token-Optimized Notation Language) for ~30-50% smaller output:

get_logs with format="tonl"

Output:

[Format: TONL - compact token-optimized format. Fields in header, values in rows.]
{logs:[{time:"14:32:45",level:"LOG",msg:"App started"},{time:"14:32:46",level:"WARN",msg:"Slow query"}]}

TONL is also available for search_logs, get_network_requests, and search_network.

Network Tracking

View Recent Requests

get_network_requests with maxRequests=20

Filter by Method

get_network_requests with method="POST"

Filter by Status Code

Useful for debugging auth issues:

get_network_requests with status=401

Search by URL

search_network with urlPattern="api/auth"

Get Full Request Details

After finding a request ID from get_network_requests:

get_request_details with requestId="123.45"

Shows full headers, request body, response headers, and timing.

Request body is truncated by default (500 chars). For full body:

get_request_details with requestId="123.45" verbose=true

Summary Mode (Recommended First Step)

Get statistics overview before fetching full requests:

get_network_requests with summary=true

This returns the same output as get_network_stats - counts by method, status, and domain.

TONL Format

Use TONL for ~30-50% smaller output:

get_network_requests with format="tonl"

View Statistics

get_network_stats

Example output:

Total requests: 47
Completed: 45
Errors: 2
Avg duration: 234ms

By Method:
  GET: 32
  POST: 15

By Status:
  2xx: 43
  4xx: 2

By Domain:
  api.example.com: 40
  cdn.example.com: 7

Debug Web Dashboard

The MCP server includes a built-in web dashboard for viewing logs and network requests in your browser. This is useful for real-time monitoring without using MCP tools.

Getting the Dashboard URL

Use the get_debug_server tool to find the dashboard URL:

get_debug_server

The server automatically finds an available port starting from 3456. Each MCP instance gets its own port, so multiple Claude Code sessions can run simultaneously.

Available Pages

Features

• Auto-refresh - Pages update automatically every 3 seconds
• Color-coded logs - Errors (red), warnings (yellow), info (blue), debug (gray)
• Expandable network requests - Click any request to see full details:
  • Request/response headers
  • Request body (with JSON formatting)
  • Timing information
  • Error details
• GraphQL support - Shows operation name and variables in compact view:

  POST  200  https://api.example.com/graphql         1ms  ▶
             GetMeetingsBasic (timeFilter: "Future", first: 20)
  

• REST body preview - Shows JSON body preview for non-GraphQL requests

JSON API Endpoints

For programmatic access, JSON endpoints are also available:

App Inspection

Discover Debug Globals

Find what debugging objects are available in your app:

list_debug_globals

Example output:

{
    "Apollo Client": ["__APOLLO_CLIENT__"],
    "Redux": ["__REDUX_STORE__"],
    "Expo": ["__EXPO_ROUTER__"],
    "Reanimated": ["__reanimatedModuleProxy"]
}

Inspect an Object

Before calling methods on an unfamiliar object, inspect it to see what's callable:

inspect_global with objectName="__EXPO_ROUTER__"

Example output:

{
    "navigate": { "type": "function", "callable": true },
    "push": { "type": "function", "callable": true },
    "currentPath": { "type": "string", "callable": false, "value": "/" },
    "routes": { "type": "array", "callable": false }
}

Execute Code in App

Run simple JavaScript expressions using globals discovered via list_debug_globals:

execute_in_app with expression="__DEV__"
// Returns: true

execute_in_app with expression="__APOLLO_CLIENT__.cache.extract()"
// Returns: Full Apollo cache contents

execute_in_app with expression="__EXPO_ROUTER__.navigate('/settings')"
// Navigates the app to /settings

Limitations (Hermes engine):

• No require() or import — only pre-existing globals are available
• No async/await syntax — use simple expressions or promise chains (.then())
• No emoji or non-ASCII characters in string literals — causes parse errors
• Keep expressions simple and synchronous when possible

React Component Inspection

Inspect React components at runtime via the React DevTools hook. These tools let you debug component state, verify layouts, and understand app structure without adding console.logs.

Recommended Workflow (Token-Efficient)

Always use the 2-step approach:

1. Step 1: Get focused screen overview (~1-3KB)

   get_component_tree with focusedOnly=true structureOnly=true
   

2. Step 2: Drill down into specific components as needed

   inspect_component with componentName="HomeScreen"
   # or
   find_components with pattern="Button" includeLayout=true
   

This approach uses ~10-20x fewer tokens than getting full details upfront.

Token Consumption Comparison

Focused Screen Mode (focusedOnly)

The focusedOnly parameter dramatically reduces output by returning only the active screen subtree:

• Skips navigation wrappers - Providers, NavigationContainers, SafeAreaProviders
• Skips global overlays - BottomSheet, Modal, Toast, Snackbar components
• Returns just the focused screen - Components matching *Screen or *Page pattern

get_component_tree with focusedOnly=true structureOnly=true

Output:

Focused: HomeScreen

HomeScreen
  Header
    Logo
    SearchBar
  FlatList
    ListItem (×12)
  Footer

When to skip focusedOnly:

• Debugging navigation structure itself
• Investigating which screens are mounted
• Checking global overlay state

Inspecting Overlays (BottomSheet, Modal, Toast)

Since focusedOnly skips global overlays by design, use this workflow to debug them:

1. Find the overlay component:

   find_components with pattern="BottomSheet|Modal|Toast"
   

2. Inspect its state/props:

   inspect_component with componentName="MyBottomSheet"
   

This targeted approach uses ~2-4KB vs ~20KB+ for the full tree.

Step 1: Get Component Tree

View the React component hierarchy with minimal data:

# Focused screen only (recommended)
get_component_tree with focusedOnly=true structureOnly=true

# Full tree structure
get_component_tree with structureOnly=true

Output (ultra-compact):

Focused: HomeScreen

HomeScreen
  Header
  FlatList
  Footer

This gives you the focused screen structure in just 1-3KB.

Step 2a: Inspect Specific Component

After identifying a component in the structure, drill down:

inspect_component with componentName="HomeScreen"

Output:

{
  "component": "HomeScreen",
  "path": "... > Navigator > HomeScreen",
  "props": {
    "navigation": "[Object]",
    "route": { "name": "Home", "key": "home-xyz" }
  },
  "hooks": [
    { "hookIndex": 0, "value": false },
    { "hookIndex": 3, "value": 42 }
  ]
}

Options:

• includeChildren=true - Include children tree
• childrenDepth=2 - How deep to show children (1=direct only, 2+=nested tree)
• includeState=false - Skip hooks/state (faster)
• index=1 - Inspect 2nd instance if multiple exist

Step 2b: Find Components by Pattern

Search for components and optionally get their layout:

find_components with pattern="Screen$" includeLayout=true

Output:

pattern: Screen$
found: 5
#found{component,path,depth,key,layout}
HomeScreen|... > Navigator > HomeScreen|45|paddingHorizontal:16|
SettingsScreen|... > Navigator > SettingsScreen|45|flex:1|

Options:

• includeLayout=true - Include flex, padding, margin values
• summary=true - Get counts only (e.g., "HomeScreen: 1")
• maxResults=10 - Limit number of results

Full Layout (Use Sparingly)

For detailed layout of all visible components:

get_screen_layout

Warning: This returns ~20-50KB for complex screens. Use find_components with includeLayout=true instead for targeted queries.

Use Cases

Figma Alignment / Layout Verification

# Step 1: See focused screen structure
get_component_tree with focusedOnly=true structureOnly=true

# Step 2: Get layout for specific components
find_components with pattern="Header|Footer|Button" includeLayout=true

Debug State Changes

# Check hook values before action
inspect_component with componentName="LoginForm"
# → hookIndex 2: false (isLoading)

# After user action, check again
inspect_component with componentName="LoginForm"
# → hookIndex 2: true (isLoading changed!)

Debug Navigation Issues

# Find which screen is currently mounted (use full tree)
get_component_tree with structureOnly=true
# or
find_components with pattern="Screen$"

# Check if a screen rendered multiple times (memory leak)
find_components with pattern="HomeScreen" summary=true

Debug Overlays (BottomSheet, Modal, Toast)

# Find and inspect overlay components
find_components with pattern="BottomSheet|Modal"

# Get overlay props/state
inspect_component with componentName="PaywallModal"

Understand Unfamiliar Codebase

# Quick focused screen overview
get_component_tree with focusedOnly=true structureOnly=true

# Full app structure (navigation, providers)
get_component_tree with structureOnly=true

# Find all button variants
find_components with pattern="Button"

# Find all context providers
find_components with pattern="Provider$"

Device Interaction

Android (requires ADB)

List connected devices:

list_android_devices

Take a screenshot:

android_screenshot

Tap on screen:

tap with x=540 y=960

Swipe gesture:

android_swipe with startX=540 startY=1500 endX=540 endY=500

Type text (tap input field first):

tap with x=540 y=400
android_input_text with text="[email protected]"

Send key events:

android_key_event with key="BACK"
android_key_event with key="HOME"
android_key_event with key="ENTER"

iOS Simulator (requires Xcode)

List available simulators:

list_ios_simulators

Boot a simulator:

ios_boot_simulator with udid="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Take a screenshot:

ios_screenshot

Launch an app:

ios_launch_app with bundleId="com.example.myapp"

Open a deep link:

ios_open_url with url="myapp://settings"

UI Interaction

Unified tap Tool (Recommended)

The tap tool is the simplest way to interact with UI elements. It automatically tries multiple strategies and handles platform detection and coordinate conversion:

# By visible text — tries fiber tree, accessibility, then OCR
tap with text="Submit"

# By testID prop
tap with testID="login-btn"

# By React component name (fiber tree only)
tap with component="HamburgerIcon"

# By pixel coordinates from screenshot (auto-converts to points on iOS)
tap with x=300 y=600

# Force a specific strategy
tap with text="Menu" strategy="ocr"

Fallback chain: fiber tree (direct onPress) → accessibility tree → OCR → error with suggestion.

On failure, the response includes an actionable suggestion telling the agent exactly what to try next.

Platform-Specific Tools

For gestures beyond tapping, use platform-specific tools:

# Swipe
ios_swipe with startX=200 startY=400 endX=200 endY=100
android_swipe with startX=540 startY=1500 endX=540 endY=500

# Text input (tap input field first)
tap with text="Email"
ios_input_text with text="[email protected]"

# Key events
android_key_event with key="BACK"
ios_button with button="HOME"

Wait for Screen Transitions

android_wait_for_element with text="Dashboard" timeoutMs=15000
ios_wait_for_element with label="Home" timeoutMs=10000

OCR Text Extraction

The ocr_screenshot tool extracts all visible text from a screenshot with tap-ready coordinates. This is useful when accessibility labels are missing or when you need to find text that isn't exposed in the accessibility tree.

Why OCR?

Usage

ocr_screenshot with platform="ios"

Returns all visible text with tap-ready coordinates:

{
  "platform": "ios",
  "engine": "easyocr",
  "processingTimeMs": 850,
  "elementCount": 24,
  "elements": [
    { "text": "Settings", "confidence": 98, "tapX": 195, "tapY": 52 },
    { "text": "Login", "confidence": 95, "tapX": 187, "tapY": 420 }
  ]
}

Then tap the element:

tap with x=187 y=420

OCR Engine

The tool uses EasyOCR (Python-based) for text recognition. It provides excellent accuracy on colored backgrounds and stylized text common in mobile UIs.

EasyOCR Setup

EasyOCR and all its Python dependencies (PyTorch, OpenCV, etc.) are installed automatically into an isolated virtual environment by the node-easyocr package — no need to run pip install manually. The only prerequisite is having Python 3.6+ available on your system:

# macOS
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3

# Windows
# Download from https://www.python.org/downloads/

On the first OCR call, language models (~100MB for English) are downloaded automatically. This may take a moment, but subsequent calls use the cached models.

OCR Language Configuration

By default, OCR recognizes English text. To add more languages, set the EASYOCR_LANGUAGES environment variable. English is always included as a fallback.

# Add Spanish and French (English always included)
EASYOCR_LANGUAGES=es,fr

Add to your MCP configuration:

{
    "mcpServers": {
        "rn-debugger": {
            "command": "npx",
            "args": ["react-native-ai-devtools"],
            "env": {
                "EASYOCR_LANGUAGES": "es,fr"
            }
        }
    }
}

See EasyOCR supported languages for the full list of language codes.

Recommended Workflow

1. Use unified tap - Handles fallback chain automatically
2. Fall back to OCR - When tap suggests using coordinates
3. Use screenshot - For visual debugging or layout verification

# Simplest approach — tap handles everything
tap with text="Submit"

# If tap fails, use OCR to find coordinates
ocr_screenshot with platform="android"

# Then tap using coordinates from OCR result
tap with x=540 y=1200

Supported React Native Versions

How It Works

1. Fetches device list from Metro's /json endpoint
2. Connects to the main JS runtime via CDP (Chrome DevTools Protocol) WebSocket
3. Enables Runtime.enable to receive Runtime.consoleAPICalled events
4. Enables Network.enable to receive network request/response events
5. Stores logs and network requests in circular buffers for retrieval

Auto-Reconnection

The server automatically handles connection interruptions:

Auto-Connect on Startup

When the MCP server starts, it automatically scans common Metro ports (8081, 8082, 19000-19002) and connects to any running Metro bundlers. No need to manually call scan_metro if Metro is already running.

Reconnection on Disconnect

When the connection to Metro is lost (e.g., app restart, Metro restart, or network issues):

1. The server automatically attempts to reconnect
2. Uses exponential backoff: immediate, 500ms, 1s, 2s, 4s, 8s (up to 8 attempts)
3. Re-fetches device list to handle new WebSocket URLs
4. Preserves existing log and network buffers

Connection Gap Warnings

If there was a recent disconnect, get_logs and get_network_requests will include a warning:

[WARNING] Connection was restored 5s ago. Some logs may have been missed during the 3s gap.

Monitor Connection Health

Use get_connection_status to see detailed connection information:

=== Connection Status ===

--- React Native (Port 8081) ---
  Status: CONNECTED
  Connected since: 2:45:30 PM
  Uptime: 5m 23s
  Recent gaps: 1
    - 2:43:15 PM (2s): Connection closed

Troubleshooting

No devices found

• Make sure the app is running on a simulator/device
• Check that Metro bundler is running (npm start)

Wrong device connected

The server prioritizes devices in this order:

1. React Native Bridgeless (SDK 54+)
2. Hermes React Native
3. Any React Native (excluding Reanimated/Experimental)

Logs not appearing

• Ensure the app is actively running (not just Metro)
• Try clear_logs then trigger some actions in the app
• Check get_apps to verify connection status

Telemetry

This package collects anonymous usage telemetry to help improve the product. No personal information is collected.

What is collected

Not collected: No file paths, code content, network data, or personally identifiable information.

Opt-out

To disable telemetry, set the environment variable:

export RN_DEBUGGER_TELEMETRY=false

Or inline:

RN_DEBUGGER_TELEMETRY=false npx react-native-ai-devtools

License

MIT