React Native Debug MCP
Allows debugging React Native apps on Android emulator or device, providing tools to capture screenshots, inspect UI, interact with the app, and view logs via ADB.
Allows debugging React Native apps on iOS simulator, providing tools to capture screenshots, inspect UI, interact with the app, and view logs via WebDriverAgent.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@React Native Debug MCP show me the current UI tree and visible elements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/ iOSsimctl)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
testIDinstead of fragile coordinatestestID 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 /
adbonPATHXcode 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-mcpAdd 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 buildAdd 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 configuredWDA_BASE_URL), the install/build is skipped entirely.Set
WDA_NO_AUTO_INSTALL=1to disable automatic installation and require manual setup.Set
WDA_BASE_URLto point to an externally managed WebDriverAgent instance.
Manual / Advanced Setup
Install WDA sources manually:
npx --no-install rndmcp install wdaRun WDA standalone:
npm run ios:wdaOptional 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:wdaTools
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? })
Recommended Agent Flow (testID-first)
get_elements_by_test_idwithtestIdMatch: "exact".If unknown IDs, call
get_screen_test_ids.If empty, retry
get_elements_by_test_idwithtestIdMatch: "contains".If still empty:
call
get_screen_contextcall
get_test_id_remediation_planpatch app code with suggested testID
call
reload_appretry exact testID lookup
If unresolved:
try
tap_elementfrom visible candidatesfallback to
tap({ x, y })use
scroll,press_back, andtype_textfor navigation/input
testID naming convention: screen.element.action (example: checkout.submit.button).
Platform Notes
connect_appdefaults toplatform: "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_iddefaults:skipVisibilityCheck: true(RN-friendly)clickableOnly: false(broader matching)
get_screen_test_idsdefault:includeInvisible: true.
Development
npm run typecheck
npm testCLI usage:
rndmcp # Start MCP server over stdio
rndmcp install wda # Clone WebDriverAgent into this packageTroubleshooting
iOS connect reports missing WDA:
WDA is auto-installed on first
connect_app({ platform: "ios" })unlessWDA_NO_AUTO_INSTALL=1set
WDA_BASE_URLto an already running WDA, orrun
rndmcp install wdaand thennpm run ios:wdafor manual setup
Reload fallbacks:
Android: ADB broadcast/key events
iOS simulator:
Cmd+Rkeyboard trigger viaosascript
Available Tools
22 toolsclose_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
Scored across 22 tools
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.
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.
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.
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
Open a React Native app in a simulated phone: read the screen, tap, type, set device state.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Drive and test your React Native and Expo apps end-to-end on iOS and Android. Supports real devices, simulators, and emulators. Snapshots, taps, typing, swipes, screenshots, deep links, reloads, builds and runtime errors.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn 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.1610 npmMIT
- AlicenseAqualityCmaintenanceEnables 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.3945,799 npmApache 2.0
- AlicenseBqualityBmaintenanceEnables 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.184MIT
- AlicenseBqualityBmaintenanceConnects 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.356 npm2MIT