React Native AI Debugger

An MCP (Model Context Protocol) server for AI-powered React Native debugging. Enables AI assistants like Claude to capture logs, execute code, inspect state, and control navigation in your React Native app.

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)

• UI Automation - Tap, 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

• Element-Based Interaction - Tap/wait for elements by text without screenshots (faster, cheaper)

• 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)

Requirements

• Node.js 18+

• React Native app running with Metro bundler

• Optional for iOS UI automation: Facebook IDB - brew install idb-companion

• Optional for enhanced OCR: Python 3.10+ with EasyOCR (see OCR Setup)

Claude Code Setup

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

Global (all projects)

Project-specific

Manual Configuration

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

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:

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

Available Tools

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

Returns:

Manual Flow (for more control):

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

Android (ADB)

iOS (Simulator)

OCR (Cross-Platform)

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

Filtering Logs

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

Start from Specific Line

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

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 - it gives you the full picture in ~10-20 tokens instead of potentially thousands:

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:

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:

TONL Format

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

Output:

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

Network Tracking

View Recent Requests

Filter by Method

Filter by Status Code

Useful for debugging auth issues:

Search by URL

Get Full Request Details

After finding a request ID from get_network_requests:

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

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

Summary Mode (Recommended First Step)

Get statistics overview before fetching full requests:

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

TONL Format

Use TONL for ~30-50% smaller output:

View Statistics

Example output:

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:

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:

Example output:

Inspect an Object

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

Example output:

Execute Code in App

Run JavaScript directly in the connected app:

Async Code

For async operations, promises are awaited by default:

Set awaitPromise=false for synchronous execution only.

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

Output:

When to skip

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

Output (ultra-compact):

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:

Output:

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:

Output:

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:

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

Use Cases

Figma Alignment / Layout Verification

Debug State Changes

Debug Navigation Issues

Debug Overlays (BottomSheet, Modal, Toast)

Understand Unfamiliar Codebase

Device Interaction

Android (requires ADB)

List connected devices:

Take a screenshot:

Tap on screen (coordinates in pixels):

Swipe gesture:

Type text (tap input field first):

Send key events:

iOS Simulator (requires Xcode)

List available simulators:

Boot a simulator:

Take a screenshot:

Launch an app:

Open a deep link:

Efficient UI Automation (No Screenshots)

For action triggering without layout debugging, use element-based tools instead of screenshots. This is 2-3x faster and uses fewer tokens.

Android - Find and Tap by Text

Search options:

• text - exact text match

• textContains - partial text (case-insensitive)

• contentDesc - accessibility content description

• contentDescContains - partial content description

• resourceId - resource ID (e.g., "button" or "com.app:id/button")

iOS - Find and Tap by Label (requires IDB)

Search options:

• label - exact accessibility label

• labelContains - partial label (case-insensitive)

• value - accessibility value

• valueContains - partial value

• type - element type (e.g., "Button", "TextField")

Wait for Screen Transitions

Both platforms support waiting with timeout:

Recommended Workflow (Priority Order)

Always try accessibility tools first, fall back to screenshots only when needed:

1. Wait for screen → Use wait_for_element with expected text/label

2. Find target → Use find_element to get tap coordinates

3. Tap → Use tap with coordinates from step 2

4. Fallback → If element not in accessibility tree, use screenshot

Why this order?

• find_element: ~100-200 tokens, <100ms

• screenshot: ~400-500 tokens, 200-500ms

When to Use Screenshots vs Element Tools

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

Returns all visible text with tap-ready coordinates:

Then tap the element:

OCR Engines

The tool uses two OCR engines with automatic fallback:

Installing EasyOCR (Optional)

For better OCR accuracy, especially on colored backgrounds and stylized text:

First run will download models (~100MB for English). Additional language models are downloaded automatically when configured. If EasyOCR is not available, the tool automatically falls back to Tesseract.js.

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 to your MCP configuration:

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

Recommended Workflow

1. Try accessibility first - Use find_element / wait_for_element (faster, cheaper)

2. Fall back to OCR - When element isn't in accessibility tree

3. Use screenshot - For visual debugging or layout verification

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:

Monitor Connection Health

Use get_connection_status to see detailed connection information:

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:

Or inline:

License

MIT