React Native AI Debugger

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

• Captures console.log, console.warn, console.error from React Native apps
• Network request tracking - capture HTTP requests/responses with headers, timing, and status
• Supports both Expo SDK 54+ (React Native Bridgeless) and RN 0.70+ (Hermes)
• Auto-discovers running Metro servers on common ports
• Filters logs by level (log, warn, error, info, debug)
• Circular buffer stores last 1000 log entries and 500 network requests
• Execute JavaScript directly in the running app (REPL-style)
• Inspect global objects like Apollo Client, Redux store, Expo Router
• Discover debug globals available in the app

Requirements

• Node.js 18+
• React Native app running with Metro bundler

Installation

Note: This package is not published to npm. Only local build installation is available.

Option 1: Clone and Build

git clone [email protected]:igorzheludkov/react-native-ai-debugger.git ~/react-native-ai-debugger
cd ~/react-native-ai-debugger
npm install
npm run build

Option 2: Manual Setup

mkdir ~/react-native-ai-debugger
cd ~/react-native-ai-debugger
npm init -y
npm install @modelcontextprotocol/sdk zod@3 ws
npm install -D @types/node @types/ws typescript

Copy the source files and build:

npm run build

Claude Code Setup

Global (all projects)

claude mcp add rn-debugger node ~/react-native-ai-debugger/build/index.js --scope user

Project-specific

claude mcp add rn-debugger node ~/react-native-ai-debugger/build/index.js --scope project

Manual Configuration

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

{
  "mcpServers": {
    "rn-debugger": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/react-native-ai-debugger/build/index.js"]
    }
  }
}

Restart Claude Code after adding the configuration.

Available Tools

Connection & Logs

Network Tracking

App Inspection & Execution

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
   

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.

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.

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

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 JavaScript directly in the connected app:

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

Async Code

For async operations, promises are awaited by default:

execute_in_app with expression="AsyncStorage.getItem('userToken')"

Set awaitPromise=false for synchronous execution only.

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

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

License

MIT