Skip to main content
Glama
React Native Debug MCP
by zersys

React Native Debug MCP

Let AI agents see, understand, and interact with your React Native app running on Android emulator or iOS simulator — through a single MCP server.

Point your MCP client at this server and an agent can connect to your app, read logs, inspect the UI, tap buttons, type text, scroll, take screenshots, and reload — all without leaving the conversation.

https://github.com/user-attachments/assets/0d5a5235-9c67-4d79-b30f-de0132be06cd

Features

Connect and Control

  • Android + iOS — one server handles both platforms

  • Multi-session — debug multiple devices or apps at the same time

  • Hot reload — reload your app instantly via Metro; automatic fallback to native reload when Metro is unavailable

See What's Happening

  • Live logs — stream device logs in real time (Android logcat / iOS simctl)

  • Error filtering — surface only errors so the agent focuses on what matters

  • Network inspector — capture HTTP requests and responses with cursor-based polling

  • Screenshots — capture the screen as a PNG image the agent can see inline

Understand the UI

  • UI tree — get the full view hierarchy (Android UIAutomator / iOS WebDriverAgent)

  • Visible elements — list what's on screen with text, bounds, and testIDs

  • Screen context — get the current activity/screen name so the agent knows where it is

Interact with the App

  • Tap, scroll, type, back — drive the app like a real user

  • Tap by testID — target elements by testID instead of fragile coordinates

  • testID discovery — list all testIDs on screen, search by exact or partial match

  • testID remediation — when a testID is missing, the agent gets a ready-to-paste code fix and can reload to verify

Related MCP server: mobile-mcp

Requirements

  • Node.js 20+

  • Android SDK / adb on PATH

  • Xcode command line tools (xcrun) and iOS Simulator (for iOS)

  • React Native app running on emulator/simulator

  • Metro running (default: 8081)

  • WebDriverAgent reachable for iOS (default: http://127.0.0.1:8100)

Quickstart

Option A: Global install (use from any project)

npm install -g rn-debug-mcp

Add to your MCP client config:

{
  "mcpServers": {
    "rn-debug": {
      "command": "npx",
      "args": ["-y", "rn-debug-mcp"],
      "env": {
        "WDA_BASE_URL": "http://127.0.0.1:8100"
      }
    }
  }
}

Option B: Local dev dependency (per-project)

npm install -D rn-debug-mcp
npm run build

Add to your MCP client config:

{
  "mcpServers": {
    "rn-debug": {
      "command": "node",
      "args": ["/ABS/PATH/TO/node_modules/rn-debug-mcp/dist/src/index.js"],
      "env": {
        "WDA_BASE_URL": "http://127.0.0.1:8100"
      }
    }
  }
}

iOS Support

iOS works automatically on first connect_app({ platform: "ios" }). WebDriverAgent sources are cloned and built transparently if not already present.

  • If WDA is already running on :8100 (or the configured WDA_BASE_URL), the install/build is skipped entirely.

  • Set WDA_NO_AUTO_INSTALL=1 to disable automatic installation and require manual setup.

  • Set WDA_BASE_URL to point to an externally managed WebDriverAgent instance.

Manual / Advanced Setup

Install WDA sources manually:

npx --no-install rndmcp install wda

Run WDA standalone:

npm run ios:wda

Optional overrides:

WDA_PROJECT_PATH="/abs/path/to/WebDriverAgent.xcodeproj" npm run ios:wda
WDA_DEVICE_ID="<booted-simulator-udid>" npm run ios:wda
WDA_DESTINATION='platform=iOS Simulator,name=iPhone 16' npm run ios:wda

Tools

Session and Connection

  • connect_app({ platform?, deviceId?, metroPort? })

  • list_sessions({})

  • set_active_session({ sessionId })

  • close_session({ sessionId })

  • get_connection_status({ sessionId? })

  • disconnect_app({ sessionId? })

  • reload_app({ sessionId? })

Logs, Errors, and Network

  • get_logs({ sessionId?, sinceCursor?, limit?, levels?, tags?, sources? })

  • get_errors({ sessionId?, sinceCursor?, limit?, levels?, tags?, sources? })

  • get_network_requests({ sessionId?, sinceCursor?, limit?, phases?, methods?, statuses?, urlContains?, sources? })

UI and Context

  • get_screen_context({ sessionId? })

  • get_ui_tree({ sessionId?, maxDepth?, maxNodes? })

  • get_visible_elements({ sessionId?, maxDepth?, maxNodes?, limit?, clickableOnly?, includeTextless?, skipVisibilityCheck?, testId?, testIdMatch? })

  • get_screen_test_ids({ sessionId?, maxDepth?, maxNodes?, limit?, includeNonClickable?, includeInvisible? })

  • get_elements_by_test_id({ sessionId?, testId, maxDepth?, maxNodes?, limit?, clickableOnly?, includeTextless?, skipVisibilityCheck?, testIdMatch? })

  • get_test_id_remediation_plan({ sessionId?, desiredAction, desiredTestId?, matchMode? })

Interaction

  • tap({ sessionId?, x, y })

  • tap_element({ sessionId?, elementId, maxDepth?, maxNodes? })

  • type_text({ sessionId?, text, submit? })

  • press_back({ sessionId? })

  • scroll({ sessionId?, direction, distanceRatio?, durationMs? })

  • take_screenshot({ sessionId? })

  1. get_elements_by_test_id with testIdMatch: "exact".

  2. If unknown IDs, call get_screen_test_ids.

  3. If empty, retry get_elements_by_test_id with testIdMatch: "contains".

  4. If still empty:

    • call get_screen_context

    • call get_test_id_remediation_plan

    • patch app code with suggested testID

    • call reload_app

    • retry exact testID lookup

  5. If unresolved:

    • try tap_element from visible candidates

    • fallback to tap({ x, y })

    • use scroll, press_back, and type_text for navigation/input

testID naming convention: screen.element.action (example: checkout.submit.button).

Platform Notes

  • connect_app defaults to platform: "android" for backward compatibility.

  • iOS tap coordinates use point space (WDA coordinates), not screenshot pixels.

  • If converting screenshot pixels to iOS points:

    • pointX = round(pixelX / scaleFactor)

    • pointY = round(pixelY / scaleFactor)

  • get_elements_by_test_id defaults:

    • skipVisibilityCheck: true (RN-friendly)

    • clickableOnly: false (broader matching)

  • get_screen_test_ids default: includeInvisible: true.

Development

npm run typecheck
npm test

CLI usage:

rndmcp                   # Start MCP server over stdio
rndmcp install wda       # Clone WebDriverAgent into this package

Troubleshooting

  • iOS connect reports missing WDA:

    • WDA is auto-installed on first connect_app({ platform: "ios" }) unless WDA_NO_AUTO_INSTALL=1

    • set WDA_BASE_URL to an already running WDA, or

    • run rndmcp install wda and then npm run ios:wda for manual setup

  • Reload fallbacks:

    • Android: ADB broadcast/key events

    • iOS simulator: Cmd+R keyboard trigger via osascript

Available Tools

22 tools
close_sessionB

Close a specific session by sessionId.

Inputs: sessionId (required).

connect_appB

Connect to a running React Native app session on Android emulator or iOS simulator and start log collection.

Inputs: platform, deviceId, metroPort.

disconnect_appC

Disconnect the active React Native app session.

Inputs: sessionId.

get_connection_statusB

Get current RN Inspector MCP session status and log buffer state.

Inputs: sessionId.

get_elements_by_test_idA

Find visible elements matching a React Native testID. Use exact first, then contains. If none, call get_screen_context + get_test_id_remediation_plan.

Inputs: testId (required), sessionId, maxDepth, maxNodes, +5 more.

get_errorsC

Read buffered error and fatal logs using cursor-based pagination.

Inputs: sessionId, sinceCursor, limit, levels, +2 more.

get_logsB

Read buffered non-error logs using cursor-based pagination.

Inputs: sessionId, sinceCursor, limit, levels, +2 more.

get_network_requestsA

Read buffered network request/response/error events using cursor-based pagination.

Inputs: sessionId, sinceCursor, limit, phases, +4 more.

get_screen_contextA

Get inferred current Android screen context for remediation guidance. Use after testID lookup fails.

Inputs: sessionId.

get_screen_test_idsB

List testIDs present on the current screen with metadata. Start UI interaction flows with this tool before get_elements_by_test_id.

Inputs: sessionId, maxDepth, maxNodes, limit, +2 more.

get_test_id_remediation_planB

Build deterministic patch/remediation guidance when a desired testID is missing. Recommended flow: get_screen_test_ids -> get_elements_by_test_id (exact/contains) -> this tool -> reload_app -> retry lookup.

Inputs: desiredAction (required), sessionId, desiredTestId, matchMode.

get_ui_treeC

Read the current accessibility hierarchy from Android UIAutomator or iOS WDA.

Inputs: sessionId, maxDepth, maxNodes.

get_visible_elementsB

Return flattened visible accessibility elements derived from the current UI tree. Use as fallback discovery after testID-first lookup.

Inputs: sessionId, maxDepth, maxNodes, limit, +5 more.

list_sessionsB

List all active MCP device sessions.

Inputs: no named parameters.

press_backC

Trigger back navigation on the current platform.

Inputs: sessionId.

reload_appC

Reload the active app session via Metro, with ADB fallback.

Inputs: sessionId.

scrollC

Scroll screen content in a direction via swipe gesture.

Inputs: direction (required), sessionId, distanceRatio, durationMs.

set_active_sessionC

Set the active session used when sessionId is omitted.

Inputs: sessionId (required).

take_screenshotC

Capture a screenshot from the connected device.

Inputs: sessionId.

tapA

Tap the screen at absolute coordinates. Final fallback only when testID and element-based targeting fail.

Inputs: x (required), y (required), sessionId.

tap_elementA

Tap a visible element by element id from get_visible_elements/get_ui_tree. Preferred fallback before coordinate tapping.

Inputs: elementId (required), sessionId, maxDepth, maxNodes.

type_textB

Type text into the currently focused input field, with optional submit/enter key press.

Inputs: text (required), sessionId, submit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool has a clear and distinct purpose, with no ambiguity between similarly named tools. For example, get_logs and get_errors are differentiated by log level, and tap vs tap_element vs type_text cover distinct interaction types.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, such as get_elements_by_test_id, connect_app, and take_screenshot. This predictability aids agent selection.

    Tool Count4/5

    With 22 tools, the server is comprehensive but slightly above the typical well-scoped range. However, each tool serves a specific debugging need, making the count acceptable.

    Completeness4/5

    The tool surface covers session management, log retrieval, UI inspection, and interaction. Minor gaps include a lack of iOS-specific screen context (only Android mentioned), but overall it supports common debugging workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that gives AI agents hands-on control of a live React Native app, enabling UI taps, screenshots, UI/component trees, native logs, and JS/React profiling to debug, verify fixes, and diagnose performance issues.
      16
      10 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables agents and LLMs to interact with native iOS and Android applications and devices via structured accessibility snapshots or coordinate-based taps, supporting simulators, emulators, and real devices.
      39
      45,799 npm
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to automate Android and iOS devices, including emulators and physical devices, by capturing screenshots, reading UI accessibility trees, performing touch and text input, and managing app lifecycle and logs.
      18
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Connects AI agents to a running React Native app so they can see the screen, tap and type, and inspect logs, network traffic, and state without any SDK or code changes. Composite tools let an agent run a whole interaction flow in a single call instead of one round trip per tap.
      35
      6 npm
      2
      MIT