React Native Debug MCP

1# React Native Debug MCP
2 
3Let AI agents see, understand, and interact with your React Native app running on Android emulator or iOS simulator — through a single MCP server.
4 
5Point 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.
6 
7https://github.com/user-attachments/assets/0d5a5235-9c67-4d79-b30f-de0132be06cd
8 
9## Features
10 
11### Connect and Control
12 
13- **Android + iOS** — one server handles both platforms
14- **Multi-session** — debug multiple devices or apps at the same time
15- **Hot reload** — reload your app instantly via Metro; automatic fallback to native reload when Metro is unavailable
16 
17### See What's Happening
18 
19- **Live logs** — stream device logs in real time (Android `logcat` / iOS `simctl`)
20- **Error filtering** — surface only errors so the agent focuses on what matters
21- **Network inspector** — capture HTTP requests and responses with cursor-based polling
22- **Screenshots** — capture the screen as a PNG image the agent can see inline
23 
24### Understand the UI
25 
26- **UI tree** — get the full view hierarchy (Android UIAutomator / iOS WebDriverAgent)
27- **Visible elements** — list what's on screen with text, bounds, and testIDs
28- **Screen context** — get the current activity/screen name so the agent knows where it is
29 
30### Interact with the App
31 
32- **Tap, scroll, type, back** — drive the app like a real user
33- **Tap by testID** — target elements by `testID` instead of fragile coordinates
34- **testID discovery** — list all testIDs on screen, search by exact or partial match
35- **testID remediation** — when a testID is missing, the agent gets a ready-to-paste code fix and can reload to verify
36 
37## Requirements
38 
39- Node.js 20+
40- Android SDK / `adb` on `PATH`
41- Xcode command line tools (`xcrun`) and iOS Simulator (for iOS)
42- React Native app running on emulator/simulator
43- Metro running (default: `8081`)
44- WebDriverAgent reachable for iOS (default: `http://127.0.0.1:8100`)
45 
46## Quickstart
47 
48### Option A: Global install (use from any project)
49 
50```bash
51npm install -g rn-debug-mcp
52```
53 
54Add to your MCP client config:
55 
56```json
57{
58  "mcpServers": {
59    "rn-debug": {
60      "command": "npx",
61      "args": ["-y", "rn-debug-mcp"],
62      "env": {
63        "WDA_BASE_URL": "http://127.0.0.1:8100"
64      }
65    }
66  }
67}
68```
69 
70### Option B: Local dev dependency (per-project)
71 
72```bash
73npm install -D rn-debug-mcp
74npm run build
75```
76 
77Add to your MCP client config:
78 
79```json
80{
81  "mcpServers": {
82    "rn-debug": {
83      "command": "node",
84      "args": ["/ABS/PATH/TO/node_modules/rn-debug-mcp/dist/src/index.js"],
85      "env": {
86        "WDA_BASE_URL": "http://127.0.0.1:8100"
87      }
88    }
89  }
90}
91```
92 
93## iOS Support
94 
95iOS works automatically on first `connect_app({ platform: "ios" })`. WebDriverAgent sources are cloned and built transparently if not already present.
96 
97- If WDA is already running on `:8100` (or the configured `WDA_BASE_URL`), the install/build is skipped entirely.
98- Set `WDA_NO_AUTO_INSTALL=1` to disable automatic installation and require manual setup.
99- Set `WDA_BASE_URL` to point to an externally managed WebDriverAgent instance.
100 
101### Manual / Advanced Setup
102 
103Install WDA sources manually:
104 
105```bash
106npx --no-install rndmcp install wda
107```
108 
109Run WDA standalone:
110 
111```bash
112npm run ios:wda
113```
114 
115Optional overrides:
116 
117```bash
118WDA_PROJECT_PATH="/abs/path/to/WebDriverAgent.xcodeproj" npm run ios:wda
119WDA_DEVICE_ID="<booted-simulator-udid>" npm run ios:wda
120WDA_DESTINATION='platform=iOS Simulator,name=iPhone 16' npm run ios:wda
121```
122 
123## Tools
124 
125### Session and Connection
126 
127- `connect_app({ platform?, deviceId?, metroPort? })`
128- `list_sessions({})`
129- `set_active_session({ sessionId })`
130- `close_session({ sessionId })`
131- `get_connection_status({ sessionId? })`
132- `disconnect_app({ sessionId? })`
133- `reload_app({ sessionId? })`
134 
135### Logs, Errors, and Network
136 
137- `get_logs({ sessionId?, sinceCursor?, limit?, levels?, tags?, sources? })`
138- `get_errors({ sessionId?, sinceCursor?, limit?, levels?, tags?, sources? })`
139- `get_network_requests({ sessionId?, sinceCursor?, limit?, phases?, methods?, statuses?, urlContains?, sources? })`
140 
141### UI and Context
142 
143- `get_screen_context({ sessionId? })`
144- `get_ui_tree({ sessionId?, maxDepth?, maxNodes? })`
145- `get_visible_elements({ sessionId?, maxDepth?, maxNodes?, limit?, clickableOnly?, includeTextless?, skipVisibilityCheck?, testId?, testIdMatch? })`
146- `get_screen_test_ids({ sessionId?, maxDepth?, maxNodes?, limit?, includeNonClickable?, includeInvisible? })`
147- `get_elements_by_test_id({ sessionId?, testId, maxDepth?, maxNodes?, limit?, clickableOnly?, includeTextless?, skipVisibilityCheck?, testIdMatch? })`
148- `get_test_id_remediation_plan({ sessionId?, desiredAction, desiredTestId?, matchMode? })`
149 
150### Interaction
151 
152- `tap({ sessionId?, x, y })`
153- `tap_element({ sessionId?, elementId, maxDepth?, maxNodes? })`
154- `type_text({ sessionId?, text, submit? })`
155- `press_back({ sessionId? })`
156- `scroll({ sessionId?, direction, distanceRatio?, durationMs? })`
157- `take_screenshot({ sessionId? })`
158 
159## Recommended Agent Flow (testID-first)
160 
1611. `get_elements_by_test_id` with `testIdMatch: "exact"`.
1622. If unknown IDs, call `get_screen_test_ids`.
1633. If empty, retry `get_elements_by_test_id` with `testIdMatch: "contains"`.
1644. If still empty:
165   - call `get_screen_context`
166   - call `get_test_id_remediation_plan`
167   - patch app code with suggested testID
168   - call `reload_app`
169   - retry exact testID lookup
1705. If unresolved:
171   - try `tap_element` from visible candidates
172   - fallback to `tap({ x, y })`
173   - use `scroll`, `press_back`, and `type_text` for navigation/input
174 
175testID naming convention: `screen.element.action` (example: `checkout.submit.button`).
176 
177## Platform Notes
178 
179- `connect_app` defaults to `platform: "android"` for backward compatibility.
180- iOS tap coordinates use point space (WDA coordinates), not screenshot pixels.
181- If converting screenshot pixels to iOS points:
182  - `pointX = round(pixelX / scaleFactor)`
183  - `pointY = round(pixelY / scaleFactor)`
184- `get_elements_by_test_id` defaults:
185  - `skipVisibilityCheck: true` (RN-friendly)
186  - `clickableOnly: false` (broader matching)
187- `get_screen_test_ids` default: `includeInvisible: true`.
188 
189## Development
190 
191```bash
192npm run typecheck
193npm test
194```
195 
196CLI usage:
197 
198```bash
199rndmcp                   # Start MCP server over stdio
200rndmcp install wda       # Clone WebDriverAgent into this package
201```
202 
203## Troubleshooting
204 
205- iOS connect reports missing WDA:
206  - WDA is auto-installed on first `connect_app({ platform: "ios" })` unless `WDA_NO_AUTO_INSTALL=1`
207  - set `WDA_BASE_URL` to an already running WDA, or
208  - run `rndmcp install wda` and then `npm run ios:wda` for manual setup
209- Reload fallbacks:
210  - Android: ADB broadcast/key events
211  - iOS simulator: `Cmd+R` keyboard trigger via `osascript`
212