Connects AI agents to running React Native apps to inspect logs, network traffic, component state, and perform UI automation.
Also known as igorzheludkov/execbro, execbro-859fd2
- Stars
- 81
- Tools
- 58
- Downloads, 30 days
- —
- Latest version
- 2.1.1
- Last commit
- Nov 15, 2026
- License
- —
What is ExecBro MCP?
ExecBro connects AI agents to running React Native apps to inspect logs, network traffic, component state, and perform UI automation. It exposes 58 tools, such as activate_license, delete_account, get_usage_guide.
Summary generated from the project's README
About ExecBro MCP server
ExecBro acts as a runtime bridge that connects AI coding agents to active React Native applications. It allows an agent to move beyond static code analysis by inspecting real-time logs, network traffic, and component states. Developers use this server to let their AI assistants observe the actual screen, perform UI automation, and verify bug fixes directly on a simulator or physical device.
Setup requires configuring the MCP server for your chosen agent and starting your React Native app via npm or expo. While it works with zero configuration, installing the optional ExecBro SDK is recommended to ensure full capture of logs and network request bodies from the very first moment an app launches. The server supports iOS simulators and Android devices through tools like simctl and ADB. It also includes experimental support for Electron and Chromium-based desktop apps using the Chrome DevTools Protocol. For security, the server includes a redaction layer that replaces sensitive credentials with handles to prevent secrets from entering the AI transcript.
What you can do with it
- 1Investigate runtime errorsAsk your AI assistant to connect to a simulator and find the cause of a specific error appearing on the screen.
- 2Test network error pathsUse response mocking to simulate offline states or failed requests to test how the app handles retries.
- 3Debug global application stateHave the agent inspect Redux or Apollo Client stores to verify that data is being updated correctly.
Written from the project's README. Every use case is checked against a quote from it.
How to install ExecBro MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ExecBro MCP in Claude Code
$ claude mcp add execbro-859fd2 -- npx -y execbroInstall ExecBro MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"execbro-859fd2": {
"command": "npx",
"args": [
"-y",
"execbro"
]
}
}
}Install ExecBro MCP in VS Code
.vscode/mcp.json
{
"servers": {
"execbro-859fd2": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"execbro"
]
}
}
}Install ExecBro MCP in VS Code CLI
$ code --add-mcp '{"name":"execbro-859fd2","type":"stdio","command":"npx","args":["-y","execbro"]}'Install ExecBro MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"execbro-859fd2": {
"command": "npx",
"args": [
"-y",
"execbro"
]
}
}
}Install ExecBro MCP in Codex
$ codex mcp add execbro-859fd2 -- npx -y execbroInstall ExecBro MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.execbro-859fd2] command = "npx" args = ["-y", "execbro"]
Install ExecBro MCP in Gemini CLI
$ gemini mcp add -s user execbro-859fd2 npx -- -y execbroInstall ExecBro MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"execbro-859fd2": {
"command": "npx",
"args": [
"-y",
"execbro"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for execbro 2.26.1 in an isolated container with no network and no keys. It answered and listed 68 tools.
ExecBro MCP tools 58
Read from the server with tools/listactivate_licenseActivate a Pro license using an activation token from your dashboard. Use this if you signed up on the website and need to link your account to this MCP installation.
delete_accountPermanently delete your account and reset this MCP installation. Removes your server-side data and local cache. You will get a new installation ID on next restart. Requires confirm: 'DELETE' to proceed.
get_usage_guideGet recommended workflows and best practices for using the debugging tools. Call without parameters to see all available topics with short descriptions. Call with a topic parameter to get the full guide for that topic.
get_license_statusGet your installation ID, license tier, and this month's usage against the free cap. Shows the Installation ID (needed to link Pro in the dashboard), current tier, cache validity, and calls used / remaining this month.
send_feedbackReport feedback about the ExecBro MCP tools THEMSELVES — a tool (tap, get_screen_layout, get_logs, etc.) that behaved incorrectly, was confusing, was missing, or could work better. This is EXCLUSIVELY about your experience operating ExecBro's debugging tools. It is NOT for bugs in the user's app under test, and NOT for the feature or task you were working on in this session — keep that out of the report entirely. Auto-collects environment info. Returns a pre-filled GitHub issue URL and formatted issue body. Ask the user to open the URL and paste the body to submit.
redux_dispatchDispatch a Redux action to the store bound to the app's <Provider>, triggering useSelector subscribers and React re-renders. Resolves the live store by walking the React fiber tree on each call (no SDK setup needed; works even if no store was registered with init()). PURPOSE: Drive state-controlled UI (loaders, modals, toasts, error overlays) without exercising the real flow (network, OTP, etc.). WHY THIS EXISTS: __RN_AI_DEVTOOLS__.stores.redux often holds a different store reference than the one passed to <Provider>, so dispatching through it updates state but does NOT notify react-redux subscribers. This tool dispatches through the actual Provider store, so views re-render. WHEN TO USE: Verify state-driven UI by seeding redux state directly. Example: dispatch app/setIsLoading: true, then ios_screenshot to confirm the loader rendered. WORKFLOW: redux_dispatch({ action: { type: 'app/setIsLoading', payload: true } }) -> ios_screenshot -> redux_dispatch({ action: { type: 'app/setIsLoading', payload: false } }). LIMITATIONS: Requires React DevTools hook (dev mode). Action must be plain JSON-serializable (no thunks/functions). If the app has multiple <Provider> roots, pass storeIndex (default 0). GOOD: redux_dispatch({ action: { type: 'app/setIsLoading', payload: true } }) BAD: redux_dispatch({ action: () => ... }) — actions must be plain objects; for thunks use execute_in_app to call your action creator.
redux_get_stateRead state from the Redux store bound to the app's <Provider>, resolved live via the fiber tree (same store redux_dispatch targets). PURPOSE: Inspect the current app state without relying on __RN_AI_DEVTOOLS__.stores.redux (which may point at a different store instance than the Provider). WHEN TO USE: Verify state shape before/after redux_dispatch, or check what slice keys exist before crafting an action. WORKFLOW: redux_get_state() -> craft action -> redux_dispatch -> redux_get_state({ path: 'app' }) to confirm. LIMITATIONS: Requires React DevTools hook (dev mode). State must be JSON-serializable; non-serializable values are replaced with an error marker. GOOD: redux_get_state({ path: 'app' }) BAD: redux_get_state({ path: 'app.isLoading.0' }) when isLoading is a boolean — path traversal returns undefined.
execute_in_appExecute JavaScript code in the connected React Native app and return the result. Use this for inspecting app state, calling methods on exposed global objects, or running diagnostic code. Hermes compatible: 'global' is automatically polyfilled to 'globalThis', so both global.__REDUX_STORE__ and globalThis.__REDUX_STORE__ work. RECOMMENDED WORKFLOW: 1) list_debug_globals to discover available objects, 2) inspect_global to see properties/methods, 3) execute_in_app to call methods or read values. LIMITATIONS (Hermes engine): - NO require() or import — only pre-existing globals are available - Async: use `Promise.resolve(foo()).then(function(r){ return r; })` (resolved for you when awaitPromise:true). `async`/`await` syntax is engine-dependent — many Hermes builds reject it. - Multi-statement input is auto-wrapped into an IIFE returning the last statement's value. If that can't yield a value (`if`/`for`/declaration), write the IIFE yourself with an explicit `return`. - Non-ASCII in string literals (emoji, Arabic, CJK) is auto-escaped server-side. Write it as-is. GOOD examples: `__DEV__`, `__APOLLO_CLIENT__.cache.extract()`, `__EXPO_ROUTER__.navigate('/settings')` BAD examples: `await fetch(...)` (bare top-level await), `require('react-native')` Pass timeoutMs (ms) for long-running expressions; capped at 120000. Auto-reconnect surfaces _meta.reconnected when a transport drop was self-healed.
list_debug_globalsList globally available debugging objects in the connected app (Apollo, Redux, React DevTools, etc.). PURPOSE: Enumerate the app's globalThis.* surface so you know which stores, clients, and debug hooks you can drill into. WHEN TO USE: Start of a state-debugging session, or when you don't know whether the app exposes a Redux/Apollo/Zustand handle. WORKFLOW: list_debug_globals -> inspect_global(objectName="...") -> execute_in_app for reads/mutations. SDK INTEGRATION: When react-native-ai-devtools-sdk's init({ stores, navigation, custom }) was called, the response includes an sdk.paths array of dotted paths (e.g. __RN_AI_DEVTOOLS__.stores.redux). Pass them to inspect_global or execute_in_app. RN NAMESPACE: The rn field reports globalThis.__rn__ — a curated set of seven RN modules (I18nManager, PixelRatio, Platform, StyleSheet, AppRegistry, NativeModules, Dimensions) populated by SDK exposeRnGlobals() or the executor's fallback bootstrap. Use paths like __rn__.Platform.OS. rn=null → bootstrap not yet run; keys=[] → ran but no match. OUTPUT: { sdk: {...}|null, rn: {keys, hint}|null, categories: {...} } LIMITATIONS: Only sees variables explicitly assigned to a global. Module-scoped state is invisible — expose it first or use the SDK.
inspect_globalInspect a global object (or a dotted path into one) to see its properties, types, and whether they are callable functions. Use this BEFORE calling methods on unfamiliar objects to avoid errors. PURPOSE: Surface the shape of a global (Apollo client, Redux store, Expo Router, SDK-registered store, etc.) — keys, types, and which members are callable — without executing arbitrary code. WHEN TO USE: After list_debug_globals identifies a promising global and before you try execute_in_app on it. WORKFLOW: list_debug_globals -> inspect_global(objectName="__APOLLO_CLIENT__") -> execute_in_app("__APOLLO_CLIENT__.cache.extract()"). DOTTED PATHS: Pass dotted paths to drill into the SDK surface, e.g. inspect_global({ objectName: "__RN_AI_DEVTOOLS__.stores.redux" }) or "__RN_AI_DEVTOOLS__.custom.mmkv". Only identifier paths are accepted — for arbitrary expressions, use execute_in_app. LIMITATIONS: Only reads one level deep; nested objects show as a 100-char JSON preview — re-inspect the child path. Returns an error object (not a throw) when the path doesn't resolve. GOOD: inspect_global({ objectName: "__APOLLO_CLIENT__" }) | inspect_global({ objectName: "__RN_AI_DEVTOOLS__.stores.redux" }) BAD: inspect_global({ objectName: "store.getState()" }) — call expressions aren't supported; use execute_in_app.
get_refresh_statusPull-style probe: did the JS runtime accept a Fast Refresh (HMR) update since `since`? Returns lastUpdateAt, updateCount, and recentUpdates from a 32-entry ring buffer fed by a recorder around __ReactRefresh.performReactRefresh (preferred) or \$RefreshReg\$ (fallback). PURPOSE: Confirm an edit landed in the running app without polling logs or screenshots. After editing TSX, wait ~2s then call with `since` = a Date.now() captured BEFORE the edit. updateCount > 0 means Fast Refresh accepted. WHEN TO USE: After editing .tsx/.ts files (prefer over reload_app). To distinguish runtime acceptance (this) from Metro build state (get_bundle_status). FILTER: `since` (epoch ms) keeps entries with at > since. `sincePath` (substring) matches modulePath — available on the \$RefreshReg\$ path but often omitted on performReactRefresh; if so the filter matches nothing — drop it. LIMITATIONS: A full reload resets the buffer (next call reports `recorder just installed`). Edits to non-React utility files still increment. Requires the React 18+ refresh runtime. SEE ALSO: get_bundle_status (did Metro compile?), get_bundle_errors (compile failures), reload_app (force full reload).
get_logsRetrieve console logs from connected React Native app. Tip: Use summary=true first for a quick overview (counts by level + last 5 messages), then fetch specific logs as needed. PURPOSE: Pull captured console output (log/warn/error/info/debug) from the in-memory buffer, and optionally native device logs (crashes, ANRs) via source="native". WHEN TO USE: Start of any log-driven investigation, verifying a code change picked up via Fast Refresh, or confirming a reported error actually fires. WORKFLOW: scan_metro -> get_logs(summary=true) -> narrow with search_logs(text="...") or get_logs(level="error") -> clear_logs between reproductions. LIMITATIONS: Circular buffer (~500 entries). Only captures logs emitted after the app connected; pre-connect logs are lost. GOOD: get_logs({ summary: true }) then get_logs({ level: "error", maxLogs: 20 }) BAD: get_logs({ maxLogs: 500, verbose: true }) as a first call — floods context; start with summary=true.
Show all 58 toolsShow fewer tools
search_logsSearch console logs for text (case-insensitive). PURPOSE: Find log lines matching a substring across the connected app's console buffer. WHEN TO USE: User reports a known error/warning, or wants to trace a specific event (e.g., "redux", "auth failed"). For unfocused exploration, prefer get_logs. WORKFLOW: scan_metro -> search_logs(text="...") -> if empty, get_logs to verify buffer populated. LIMITATIONS: Only matches text captured AFTER the app connected; won't find pre-connect logs. GOOD: search_logs({ text: "TypeError" }) BAD: search_logs({ text: "" }) (use get_logs for a raw dump)
clear_logsClear the log buffer. PURPOSE: Empty the in-memory console buffer (and the SDK buffer if installed) so the next get_logs / search_logs only sees fresh entries. WHEN TO USE: Before reproducing a bug so the resulting logs are isolated; between test iterations to avoid noise from earlier runs. WORKFLOW: clear_logs -> reproduce the issue (tap / navigate / reload_app) -> get_logs or search_logs. GOOD: clear_logs() right before tap(text="Submit") BAD: clear_logs() AFTER the repro — you just deleted the evidence.
get_log_detailsGet the full payload of a single log event — complete stack trace, backtrace, or oversized message. PURPOSE: Expand one row from get_logs into its full text. A crash row collapses a 60-line backtrace; this returns all of it. WHEN TO USE: After get_logs shows an event you need to read in full (a crash, an exception, a large payload). WORKFLOW: get_logs -> copy the id (e.g. "n7") -> get_log_details(id="n7"). LIMITATIONS: Ids are valid until that device's buffer rolls over or clear_logs runs, not for the whole server session — call get_logs again to get fresh ones. Reads the buffer — it does not re-query the device. GOOD: get_log_details({ id: "n7" }) BAD: Guessing ids — always take them from get_logs.
get_network_requestsRetrieve captured network requests from connected React Native app. Shows URL, method, status, and timing. Note: On Bridgeless targets (Expo SDK 52+) without the SDK, capture may miss early startup requests. Install execbro-sdk for full capture with headers and response bodies. Tip: Use summary=true first for stats overview. PURPOSE: Inspect HTTP traffic the app made since connection — URLs, methods, status codes, and timings — to debug API, auth, and caching issues. WHEN TO USE: User reports a failed login/load, slow screen, or wrong data. Confirm a request fired, check its status, and pivot to get_request_details for headers/body. WORKFLOW: scan_metro -> reproduce action -> get_network_requests({ summary: true }) -> get_network_requests({ status: 500 }) or search_network -> get_request_details(id). LIMITATIONS: Bridgeless targets without the SDK may miss pre-connect requests and response bodies — install execbro-sdk for full fidelity. GOOD: get_network_requests({ summary: true }) then get_network_requests({ urlPattern: "/login", status: 401 }) BAD: get_network_requests({ maxRequests: 500 }) as the first call — start with summary=true.
search_networkSearch network requests by URL pattern (case-insensitive). PURPOSE: Filter the network buffer to requests whose URL matches a substring — fast way to find a specific endpoint in a noisy app. WHEN TO USE: You know part of the URL (e.g., "/graphql", "users", a domain) and want matching requests across all devices. WORKFLOW: search_network(urlPattern="/api/") -> get_request_details(requestId="...") for full headers/body. LIMITATIONS: Matches URL only; for method/status/body filtering use get_network_requests. Bodies are only present when the SDK is installed. GOOD: search_network({ urlPattern: "/graphql" }) BAD: search_network({ urlPattern: "" }) — empty pattern matches everything; use get_network_requests instead.
get_request_detailsGet full details of a specific network request including headers, body, and timing. With the SDK installed, includes full request/response bodies. Without SDK, bodies are not available on most targets. Use get_network_requests first to find the request ID. PURPOSE: Drill into a single network entry — full request/response headers, body, status, and timing breakdown. WHEN TO USE: After get_network_requests or search_network returns a suspect ID and you need the payload to diagnose. WORKFLOW: get_network_requests / search_network -> copy id -> get_request_details(requestId). LIMITATIONS: Bodies require the execbro-sdk in the app; on CDP-only targets response bodies are missing. Large bodies are truncated — raise maxBodyLength. GOOD: get_request_details({ requestId: "42", maxBodyLength: 4000 }) BAD: Guessing requestIds — always get them from get_network_requests / search_network first.
clear_networkClear the network request buffer. PURPOSE: Reset the captured request list to isolate new traffic from a specific user action. WHEN TO USE: Right before reproducing a bug so the buffer contains only the relevant requests. WORKFLOW: clear_network -> trigger action (tap, execute_in_app) -> get_network_requests / search_network. LIMITATIONS: Irreversible — cleared requests cannot be recovered. Also clears the SDK's in-app buffer when SDK is present. GOOD: clear_network() before a reproduction. BAD: Using clear_network as a workaround for stale connections — use scan_metro / ensure_connection instead.
app_requestIssue an HTTP request from inside the running app, as the logged-in user. PURPOSE: Probe your backend through the app's real network stack, TLS trust and proxy config — without pasting credentials into the conversation. WHY THIS EXISTS: hand-written fetch calls either dig the token out of redux or embed a JWT literal in the expression, which puts the credential in the transcript. auth="auto" resolves it in-app instead. WHEN TO USE: reproduce a 4xx, check what an endpoint returns for an edge case, clean up test records the UI can't reach. WORKFLOW: app_request({ method: "GET", url: "https://api.example.com/me" }) -> inspect status + body. LIMITATIONS: needs a connected app. Token lookup covers state.user.accessToken, state.auth.accessToken and state.auth.token; pass an explicit Authorization header if your app stores it elsewhere. GOOD: app_request({ method: "DELETE", url: "https://api.example.com/address/17" }) BAD: embedding a bearer token in an execute_in_app expression — it lands in the transcript.
navigateNavigate the app's router directly, and verify it actually moved. PURPOSE: Jump to a screen without tapping through the UI, with a settled before/after route check. WHY THIS EXISTS: hand-written router calls report success whenever nothing throws. A path sent to a React Navigation ref changes nothing and warns only in LogBox, so a no-op reads as a success. DESTINATIONS ARE NOT INTERCHANGEABLE: Expo Router takes paths ("/event-details?id=1"); React Navigation takes route names ("TarotNav"). The response reports which router resolved. Unknown React Navigation names are rejected before dispatch, with nearest-match suggestions. WORKFLOW: navigate({ to: "/settings" }) -> check changed -> get_screen_state. LIMITATIONS: push/replace are unavailable on a React Navigation root ref (stack-scoped). changed=false means it settled without moving; indeterminate=true means no settled reading. GOOD: navigate({ to: "TarotNav" }); navigate({ action: "back" }) BAD: navigate({ to: "/TarotNav" }) on React Navigation — that is a path, not a route name.
logboxInteract with React Native's LogBox overlay (dev mode only). Actions: "dismiss" clears all entries and returns their content. "push" displays a message in the LogBox error banner (visible to the developer watching the device). "ignore" adds patterns to suppress future LogBox entries for this session. "detect" reads current LogBox state without modifying it. Only works in __DEV__ mode — LogBox does not exist in production builds. PURPOSE: Control RN's on-device red/yellow overlay — clear it when it blocks UI, suppress noisy repeats, or push a message back to the developer. WHEN TO USE: Screenshot/tap reports LogBox is obstructing the screen, an error banner prevents interaction, or you want to surface info to the dev watching the simulator. WORKFLOW: logbox(action="detect") -> if present: logbox(action="dismiss") to read + clear -> continue UI work. Use action="ignore" with patterns to stop repeat noise. LIMITATIONS: Dev-only — no effect in production builds. "push" at level="warning" won't show a banner unless LogBox is already open. GOOD: logbox({ action: "dismiss" }); logbox({ action: "ignore", patterns: ["[APOLLO]"] }) BAD: Spamming logbox(action="push") for every tool step — annoys the developer.
get_bundle_statusGet the current Metro bundler status including build state and any recent bundling errors. Use this to check if there are compilation/bundling errors that prevent the app from loading. PURPOSE: Snapshot Metro's current build state (idle / transforming / error) together with any captured errors — a fast "is the bundler healthy?" check. WHEN TO USE: Before diving into runtime debugging — rules out compile-time failures that would make get_logs and tap pointless. WORKFLOW: get_bundle_status -> if errors present: get_bundle_errors for detail -> fix -> get_bundle_errors({ clear: true }). LIMITATIONS: Relies on Metro's WebSocket event stream; if Metro isn't running or the connection dropped, status may be stale. GOOD: get_bundle_status() at the start of a debug session. BAD: Polling every second — Metro events are push-based; just call once and act on the result.
get_bundle_errorsRetrieve captured Metro bundling/compilation errors. These are errors that occur during the bundle build process (import resolution, syntax errors, transform errors) that prevent the app from loading. If no errors are captured but Metro is running without connected apps, automatically falls back to screenshot+OCR to capture the error from the device screen. PURPOSE: Surface Metro's build-time failures (not runtime JS errors) that keep the app from booting or hot-reloading. WHEN TO USE: App shows the red error screen, refuses to connect, or Fast Refresh stops working after an edit. Also use when get_logs is silent but the app is clearly broken. WORKFLOW: get_bundle_status -> get_bundle_errors -> fix source -> get_bundle_errors({ clear: true }) -> reload_app. LIMITATIONS: Captures errors Metro emits via its WebSocket; the screenshot+OCR fallback requires a booted simulator and the platform param. GOOD: get_bundle_errors({ platform: "ios" }); get_bundle_errors({ clear: true }) after fixing, so the next read reflects only new errors. BAD: Using get_bundle_errors to look for runtime TypeErrors — those live in get_logs, not the bundler.
list_devicesList every iOS simulator, Android emulator, and connected physical device on the host machine, in one structured response. PURPOSE: Single discovery entry point. Returns booted+shutdown iOS sims (from simctl), running+stopped Android emulators (from `emulator -list-avds` cross-referenced with `adb devices`), and attached physical devices. Each row is enriched with `rnConnected` when an RN app from get_apps matches the same identifier. WHEN TO USE: Before tap/swipe to pick a device, when a tool reports an ambiguous-device error, or to check whether a simulator is booted before targeting it. WORKS WITHOUT RN: No Metro connection required. Safe to call before scan_metro. WORKFLOW: list_devices -> tap({ device: '<udid-or-serial-or-name>', ... }) SEE ALSO: get_apps for RN-specific connection details (RN version, JS engine, network capture mode).
android_launch_appLaunch an app on an Android device/emulator by package name [PLATFORM-SPECIFIC — no cross-platform equivalent; use when launching an Android app by package name] PURPOSE: Start an installed Android app by its package (and optional activity) so the next tool calls hit a running process. WHEN TO USE: After a force-stop or install, or when the app isn't foregrounded before interaction.
android_list_packagesList installed packages on an Android device/emulator [PLATFORM-SPECIFIC — no cross-platform equivalent; use when listing installed Android packages] PURPOSE: Enumerate package names visible to adb so you can confirm installation or pick the right target for android_launch_app. WHEN TO USE: Before android_launch_app when you don't know the exact package name, or to verify an install succeeded.
ios_launch_appLaunch an app on an iOS simulator by bundle ID [PLATFORM-SPECIFIC — no cross-platform equivalent; use when launching an iOS app by bundle ID] PURPOSE: Start an installed iOS app by its bundle ID so the next tool calls hit a running process. WHEN TO USE: After ios_terminate_app or an install, or when the app isn't foregrounded before interaction.
ios_open_urlOpen a URL in the iOS simulator (opens in default handler or Safari). PURPOSE: Drive an iOS simulator into a deep link or universal link entry point so you can exercise routing from an external entry. WHEN TO USE: Testing deep-link handlers, universal link routing, OAuth/SSO callback URLs, or any flow that enters the app via a URL. WORKFLOW: ios_boot_simulator -> ios_launch_app (or have the app running) -> ios_open_url -> ios_screenshot / get_screen_layout to verify the target screen rendered. GOOD: ios_open_url(url="myapp://product/42") to land directly on a product screen. BAD: ios_open_url(url="...") used as a substitute for in-app navigation when the user would normally tap — prefer `tap` for normal interaction flows. [PLATFORM-SPECIFIC — no cross-platform equivalent; use when testing iOS deep links or universal links]
ios_terminate_appTerminate a running app on an iOS simulator [PLATFORM-SPECIFIC — no cross-platform equivalent; use when force-terminating an iOS app] PURPOSE: Force-kill an iOS app process so the next launch starts from a cold state. WHEN TO USE: To reset app state fully (beyond what reload_app does), or before reinstalling a new build.
ios_boot_simulatorBoot an iOS simulator by UDID. PURPOSE: Bring a specific simulator online so you can install/launch an app in it. WHEN TO USE: At session start when no simulator is running, or after switching between device models. [PLATFORM-SPECIFIC — no cross-platform equivalent; use when booting an iOS simulator] Use list_devices to find available simulators.
scan_metroScan for running Metro bundler servers and automatically connect to any found React Native apps. This is typically the FIRST tool to call when starting a debugging session - it establishes the connection needed for other tools like get_logs, list_debug_globals, execute_in_app, and reload_app. PURPOSE: Discover Metro on ports 8081-8090 and auto-connect all React Native debugger targets it advertises. WHEN TO USE: At the start of any session, or after the user restarts Metro / boots a new simulator. WORKFLOW: scan_metro -> get_apps -> get_logs / ios_screenshot / tap. GOOD: scan_metro() BAD: scan_metro() called repeatedly in a loop — use ensure_connection to re-verify an existing connection.
ensure_connectionVerify or establish a healthy connection to a React Native app. Use before running commands if connection may be stale, or after navigation/reload. This tool runs a health check and will auto-reconnect if needed. PURPOSE: Health-check the existing CDP connection and transparently reconnect if it has gone stale, without rescanning all Metro ports. WHEN TO USE: After a suspected disconnect (silent gaps, reload_app, app crash) or before long-running flows where a mid-flow drop would be costly. Cheaper than scan_metro when you already connected once this session. WORKFLOW: scan_metro (once) -> ensure_connection(healthCheck=true) -> resume tool calls. Use forceRefresh=true if the first probe still looks dead. GOOD: ensure_connection({ healthCheck: true }) BAD: ensure_connection() before scan_metro has ever run — call scan_metro first.
get_appsList currently connected React Native apps and their connection status. If no apps are connected, run scan_metro first to establish a connection. PURPOSE: Enumerate active debug targets with device names, platforms, ports, and detected RN/Expo versions so you can target the right one. WHEN TO USE: After scan_metro to confirm what connected, or before passing a device="..." filter to another tool. WORKFLOW: scan_metro -> get_apps -> get_logs / ios_screenshot / tap (with device="..." if multiple). LIMITATIONS: Only lists devices the MCP has successfully connected to — stale targets don't appear here, use get_connection_status for health details. GOOD: get_apps() BAD: Calling get_apps in a tight loop — the list doesn't change without a scan_metro or disconnect_metro.
get_connection_statusGet detailed connection health status including uptime, recent disconnects/reconnects, and connection gaps that may indicate missing data. PURPOSE: Diagnose flaky CDP sessions — quantify uptime, count reconnects, and expose gaps where logs/network data could be missing. WHEN TO USE: When logs look suspiciously empty, tools complain about disconnect/reconnect, or the app was suspended and resumed. WORKFLOW: get_connection_status -> if unhealthy: disconnect_metro -> scan_metro to rebuild a clean session. LIMITATIONS: Reports only MCP-side view; doesn't know why Metro dropped the socket (simulator sleep, app backgrounded, etc). GOOD: get_connection_status() after noticing stale data. BAD: Polling get_connection_status as a heartbeat — use ensure_connection(healthCheck=true) for a live probe. Pass events=true to include the recent connection event log (connect/close/reconnect lifecycle) — useful when a target drops mid-session and you need to see why reconnect didn't recover it.
connect_metroConnect to a Metro server on a specific port — the only way to reach a port scan_metro does not probe. PURPOSE: Establish a CDP WebSocket connection to a Metro server on a known port. WHEN TO USE: Metro is on a port outside 8081-8090. For any port in that range, scan_metro is strictly better — it probes them all and attaches every Bridgeless target in one call, where this connects to one port only. SEE ALSO: scan_metro for auto-discovery; get_apps afterwards to confirm the device attached.
disconnect_metroDisconnect from Metro servers and stop auto-reconnection. Without device param: disconnects ALL devices. With device param: disconnects only the matching device. Use this to remove stale connections or free the CDP slot for the built-in debugger. Log and network buffers are preserved. Reconnect later with scan_metro. PURPOSE: Cleanly release CDP slots so another debugger (Flipper, React DevTools, Chrome) can attach, or nuke a stale connection the MCP keeps reviving. WHEN TO USE: Before launching a native debugger, when connections keep flapping, or after a simulator/device restart left zombie targets. WORKFLOW: disconnect_metro -> attach other debugger / restart app -> scan_metro to reconnect. LIMITATIONS: Suppresses auto-reconnect until scan_metro or connect_metro is called again; buffers persist but won't receive new events. GOOD: disconnect_metro(); disconnect_metro({ device: "iPhone" }) BAD: Using disconnect_metro to clear logs — use clear_logs instead; disconnect breaks capture.
reload_appReload the React Native app (triggers JavaScript bundle reload like pressing 'r' in Metro). PURPOSE: Force a full JS bundle reload when Fast Refresh isn't enough — clears in-memory state and re-runs the bundle from scratch. WHEN TO USE (only these cases): (1) native code, app.json, Info.plist, Podfile, or a native module changed; (2) Fast Refresh visibly failed (red-screen or stale render confirmed via screenshot after a few seconds); (3) the app is in a broken state; (4) you need to reset app state completely; (5) the user explicitly asks. AVOID: reloading reflexively after JS/TS/TSX/style edits — Fast Refresh applies those in 1-2s. A reload discards navigation stack, context, hooks state, BLE/WebSocket connections, paired devices, and auth sessions, which can force re-pairing or re-login and break your verification loop. WORKFLOW: screenshot → wait 2s for Fast Refresh → if still stale, reload_app. Auto-connects to Metro if no connection exists (with or without a device argument) — no need to call scan_metro first. After reload, wait a few seconds before running other tools. SEE ALSO: get_refresh_status (did Fast Refresh accept?), get_bundle_status (did Metro compile?).
ios_screenshotTake a screenshot from an iOS simulator. Returns the image plus a screen-state summary: active route (name + navigation stack), overlay-grouped tappable elements (pressables behind an open sheet/modal are excluded), component names as JSX tags, labels, testIDs, and frames — all in ready-to-tap pixel coordinates. Prefer tap(text="...") when text is exact and unique; otherwise use tap(x, y) with coordinates from the list — this is the most reliable way to tap icons or visually-identified elements. Use component names for inspect_component/find_components. PURPOSE: Snapshot what the user sees on iOS AND get tap-ready pressables + a structured component map in one call. WHEN TO USE: Any visual verification, before/after comparison, or as the starting point for tapping UI by coordinates. WORKFLOW: ios_screenshot -> pick element from pressables -> tap(x, y) or tap(testID=...) -> ios_screenshot to verify. LIMITATIONS: Requires a booted iOS simulator (simctl). For physical devices or system dialogs without RN, combine with tap(..., native=true). GOOD: ios_screenshot() BAD: ios_screenshot({ udid: "guess" }) with a made-up UDID — run list_devices first. SOURCE: to jump from a pixel to the code that renders it, call inspect_at_point(x, y) — it returns the absolute file and line.
android_screenshotTake a screenshot from an Android device/emulator. Returns the image plus a screen-state summary: active route (name + navigation stack), overlay-grouped tappable elements (pressables behind an open sheet/modal are excluded), component names as JSX tags, labels, testIDs, and frames — all in ready-to-tap pixel coordinates. Prefer tap(text="...") when text is exact and unique; otherwise use tap(x, y) with coordinates from the list — this is the most reliable way to tap icons or visually-identified elements. Use component names for inspect_component/find_components. PURPOSE: Snapshot what the user sees on Android AND get tap-ready pressables + a structured component map in one call. WHEN TO USE: Any visual verification, before/after comparison, or as the starting point for tapping UI by coordinates on Android. WORKFLOW: android_screenshot -> pick element from pressables -> tap(x, y) or tap(testID=...) -> android_screenshot to verify. LIMITATIONS: Requires adb in PATH and a running device/emulator. For non-RN surfaces (system dialogs, permission prompts), combine with tap(..., native=true). GOOD: android_screenshot() BAD: android_screenshot({ deviceId: "guess" }) with a made-up serial — run list_devices first. SOURCE: to jump from a pixel to the code that renders it, call inspect_at_point(x, y).
get_imagesAccess the shared image buffer containing screenshots from all tools (ios_screenshot, android_screenshot, ocr_screenshot, tap verification). Returns metadata only by default — use id or groupId+frameIndex to retrieve actual image data. Tap burst verification stores frame groups here when burst=true is used. PURPOSE: Retrieve prior screenshots — especially tap burst frames — without re-taking them, for visual diffing or reviewing transient UI states. WHEN TO USE: After tap(burst=true) reports transientChangeDetected, or to compare before/after frames without another screenshot round-trip. WORKFLOW: tap(burst=true) -> note verification.burstGroupId -> get_images(groupId, frameIndex=N) to inspect individual frames. LIMITATIONS: Circular buffer (50 entries) — old images are evicted. Metadata is cheap; fetching image data is not — request specific ids, not bulk. GOOD: get_images({ list: true }); get_images({ groupId: "burst-abc", frameIndex: 2 }) BAD: get_images() with no filter when buffer is full — floods context. Use list:true or last:N first.
ocr_screenshotRECOMMENDED: Use this tool FIRST when you need to find and tap UI elements. Takes a screenshot and extracts all visible text with tap-ready coordinates using OCR. ADVANTAGES over accessibility trees: (1) Works on ANY visible text regardless of accessibility labels, (2) Returns ready-to-use tapX/tapY coordinates - no conversion needed, (3) Faster than parsing accessibility hierarchies, (4) Works consistently across iOS and Android. USE THIS FOR: Finding buttons, labels, menu items, tab bars, or any text you need to tap. Simply find the text in the results and use its tapX/tapY with the tap command. PURPOSE: Visually locate text on screen and return coordinates safe to pass straight into tap. WHEN TO USE: Non-RN surfaces, third-party WebViews, accessibility-poor screens, or when fiber/testID strategies have failed. WORKFLOW: ocr_screenshot(platform="ios") -> scan results for the label -> tap(x=tapX, y=tapY) -> ios_screenshot to verify. LIMITATIONS: OCR accuracy degrades on very small or stylized text; icons with no label won't appear — use tap(component=...) instead. GOOD: ocr_screenshot({ platform: "ios" }) BAD: ocr_screenshot used just to view the screen — plain ios_screenshot / android_screenshot is cheaper when you don't need OCR text. SOURCE: for RN screens, inspect_at_point(x, y) returns the file and line that render an element — no OCR needed.
tapTap a UI element. Automatically tries multiple strategies: fiber tree (React), accessibility tree (native), and OCR (visual). [PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings] PURPOSE: Single unified tap entry point — resolves text/testID/component/coordinates into a real touch event on the correct device. WHEN TO USE: Any time you need to press a button, focus an input, open a menu, or verify a handler fires. Prefer testID, then text, then component, then (x,y) from a screenshot's pressables list. WORKFLOW: ios_screenshot or android_screenshot -> tap(testID="...") | tap(text="...") | tap(x, y) -> screenshot again to verify. Use burst=true when meaningful=false but visual feedback looks transient. LIMITATIONS: iOS needs AXe (brew install cameroncooke/axe/axe) or IDB for accessibility/coordinate taps. Non-ASCII text skips fiber (Hermes); prefer testID. Pass `device` to target a specific simulator/emulator when multiple are available — call list_devices for the inventory. GOOD: tap({ testID: "login-btn" }); tap({ text: "Submit" }); tap({ x: 300, y: 600 }); tap({ x: 300, y: 600, native: true, device: "emulator-5554" }) BAD: tap({ text: "" }) or tap({ x: 0, y: 0 }) — missing a target. tap({ text: "Submit" }) without first screenshotting an ambiguous screen. SOURCE: need the file:line that renders an element? inspect_at_point(x, y).
android_long_pressLong press at specific coordinates on an Android device/emulator screen [PLATFORM FALLBACK — prefer `tap` for short taps; keep android_long_press for long-press gestures specifically unless you specifically need native-only behavior] PURPOSE: Emit a sustained touch at raw pixel coordinates to trigger long-press handlers (context menus, drag starts, multi-select). WHEN TO USE: Only when a long-press gesture is required — regular taps should go through `tap`.
swipeSwipe gesture that auto-routes to the correct platform (iOS or Android), with pixel-diff verification. [PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings] PURPOSE: Single unified swipe entry point. Easiest form: swipe({ direction: "up" }) scrolls to reveal more content ("down"/"left"/"right" also work; bare swipe() defaults to "up"). Optional distance in screenshot pixels (default 33% of axis). For precise control, pass all four coordinates (startX/startY/endX/endY) — they take precedence over direction. WHEN TO USE: Scrolling lists, paging carousels, pull-to-refresh, dismissing sheets, opening drawers — anything that needs a gesture rather than a tap. Especially useful in virtualized lists (FlatList/SectionList) where off-screen items aren't mounted in the fiber tree. VERIFICATION: verify=true (default) returns `verification.meaningful` — false means the scroll did nothing (end-of-list, non-scrollable surface, or missed coordinates). burst=true catches transient feedback like overscroll bounce. WORKFLOW: swipe({ direction: "up" }) -> read response.verification.meaningful. Advanced: pass startX/startY/endX/endY for coordinate-precise gestures. LIMITATIONS: iOS needs AXe (brew install cameroncooke/axe/axe) or IDB. Pass `device` to target a specific simulator/emulator when multiple are available — call list_devices for the inventory.
android_input_textType text on an Android device/emulator. [PLATFORM FALLBACK — prefer `tap(text=...)` — it auto-focuses TextInput via the fiber tree unless you specifically need native-only behavior] The text will be input at the current focus point (tap an input field first). PURPOSE: Send keystrokes to whichever input currently has focus on Android — the tool does NOT focus a field itself. WHEN TO USE: Only after an input is already focused, or when `tap(text=...)` on the input didn't take focus for some reason. PREREQUISITE: A TextInput must already have focus. Tap the field first (e.g. tap({ testID: 'search' })) — `android_input_text` does NOT focus a field itself; replace:true also requires React focus. REPLACE MODE: pass replace:true to clear the focused field first (via React onChangeText so controlled state stays consistent), then type the new value. Use for pre-filled fields where appending would corrupt the value.
android_key_eventSend a key event to an Android device/emulator. [PLATFORM-SPECIFIC — no cross-platform equivalent; use when sending Android key events (BACK, HOME, MENU, etc.)] Common keys: HOME, BACK, CALL, END_CALL, VOLUME_UP, VOLUME_DOWN, POWER, CAMERA, CLEAR, TAB, ENTER, DEL, MENU, SEARCH, MEDIA_PLAY_PAUSE, MEDIA_STOP, MEDIA_NEXT, MEDIA_PREVIOUS, MOVE_HOME, MOVE_END, APP_SWITCH, ESCAPE PURPOSE: Dispatch Android system keys (BACK, HOME, MENU, ENTER, DEL, etc.) that aren't reachable via on-screen tap. WHEN TO USE: Navigate back from a screen, submit a form with ENTER, dismiss the keyboard, or press hardware-style keys during a flow.
ios_buttonPress a hardware button on an iOS simulator. [PLATFORM-SPECIFIC — no cross-platform equivalent; use when pressing iOS hardware buttons (HOME, LOCK, SIRI, APPLE_PAY)] Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion). PURPOSE: Trigger iOS hardware buttons (HOME, LOCK, SIDE_BUTTON, SIRI, APPLE_PAY) that aren't reachable via on-screen tap. WHEN TO USE: Send the app to background (HOME), lock the simulator (LOCK), or exercise Siri/Apple Pay flows.
dismiss_keyboardBlur the currently focused TextInput, dismissing the on-screen keyboard. PURPOSE: Close the keyboard when it's blocking content beneath the input, or move focus off an input before a tap that would otherwise be intercepted. WHEN TO USE: After typing into a field and before tapping a button that is hidden by the keyboard. Or to verify a 'tap outside dismisses' UX is wired up. PREREQUISITE: A TextInput must already have React focus. Tap the field first (e.g. tap({ testID: 'search' })). LIMITATIONS: Requires Bridgeless/Fabric (RN new architecture). Returns 'no focused TextInput' if nothing is focused.
ios_input_textType text on an iOS simulator. [PLATFORM FALLBACK — prefer `tap(text=...)` — it auto-focuses TextInput via the fiber tree unless you specifically need native-only behavior] The text is typed into whichever field currently has focus (tap an input first). Mirrors `android_input_text` so cross-platform agents can use `<platform>_input_text` without branching on the iOS driver shell-out. PURPOSE: Send keystrokes to the focused field on an iOS simulator via the active UI driver (AXe — preferred — or IDB). WHEN TO USE: Only after an input is already focused, or when `tap(testID=...)` on the input didn't take focus for some reason. Use the testID-first flow whenever possible — it's faster and survives UI repositioning. REPLACE MODE: pass replace:true to clear the focused field first (via React onChangeText so controlled state stays consistent), then type the new value. Use for pre-filled fields where appending would corrupt the value. LIMITATIONS: AXe types via the US-keyboard HID — non-ASCII characters (Cyrillic, CJK, Arabic) may not transmit correctly. If the active driver is AXe and the text contains non-ASCII chars, prefer pasting via the simulator pasteboard or setting IOS_DRIVER=idb.
get_screen_layoutGet a screen map showing visible components as an indented tree with actual screen positions. Uses measureInWindow for real coordinates and filters out off-screen components. Returns meaningful component names with text content and frame data (x,y width x height). Coordinates are in **points** (iOS) or **dp** (Android) — NOT screenshot pixels. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.). [PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings] PURPOSE: Quickest textual map of what is actually on screen right now — component names, positions, and text — so you can plan taps and inspections without guessing. WHEN TO USE: First step whenever the user asks "what's on screen", "why is X covering Y", or before tapping a visually ambiguous element. WORKFLOW: get_screen_layout -> find_components(pattern="...") or inspect_component(componentName="...") -> tap(testID=...) -> get_screen_layout again to confirm. LIMITATIONS: pass coordinates straight to tap(), which handles conversion — never multiply by devicePixelRatio yourself. GOOD: get_screen_layout({ extended: true }) BAD: get_screen_layout({ summary: true }) when you actually need to pick a specific element — summary hides the tree. SOURCE: file:line for an element? inspect_at_point(x, y).
get_component_treeGet the React component tree from the running app — the fiber hierarchy including providers, navigation wrappers, and internal components. For a screen overview with positions and text, use get_screen_layout instead. Returns compact names-only structure by default; pass structureOnly=false for the full detailed tree. PURPOSE: Expose the entire fiber tree — including providers, navigators, and off-screen subtrees — when get_screen_layout's visible-only view isn't enough. WHEN TO USE: Debugging context propagation, navigation wrappers, hidden modals, or when you need to understand the full React architecture. WORKFLOW: get_component_tree() for overview -> find_components for targeted lookup -> inspect_component for props/state. LIMITATIONS: The detailed tree (structureOnly=false) is very large and routinely exceeds response-size limits on real apps — reach for inspect_component on a specific node instead. Ignores non-React native views. Minified builds return display names that may be opaque. GOOD: get_component_tree() BAD: get_component_tree({ structureOnly: false, includeProps: true, includeStyles: true }) on a large app — prefer inspect_component for specific nodes.
get_pressable_elementsPrefer get_screen_state after navigation (route + overlays + pressables in one call). Find all pressable (onPress) and input (TextInput) elements currently visible on screen. Returns component names, ready-to-tap center coordinates in SCREENSHOT PIXELS (same space as ios_screenshot/android_screenshot — pass directly to tap(x, y)), text labels, testID, accessibilityLabel, and a spatial nearbyText hint for icon-only buttons. Each element includes hasLabel (true if it contains text) and isInput (true for TextInput fields). HELPER — call before `tap` when you need to enumerate candidate elements before committing to a target; not a replacement for tap itself. PURPOSE: Produce a ready-to-tap inventory of every interactive element on screen with screenshot-pixel coordinates that tap(x, y) accepts directly. WHEN TO USE: Before tapping icon-only buttons, when text-based tap keeps failing, or to enumerate what the user can actually interact with. WORKFLOW: ios_screenshot / android_screenshot -> get_pressable_elements -> tap(testID="...") or tap(x, y) using the center coordinates. LIMITATIONS: Visible-only (off-screen pressables are excluded). Requires a live React connection. Coordinates are in screenshot pixels — the tap tool converts to points internally. GOOD: get_pressable_elements() BAD: Calling when tap(testID="...") already works — testID matching is faster and more stable.
get_screen_stateScreenshot-free snapshot of the current screen: active route + params, blocking overlays (sheets, modals, alerts), and every on-screen element merged top-to-bottom within reachability groups. Call after any tap or navigation to orient before the next action. Each line carries an (x, y) center + frame bounds (so anything is a tap(x, y) target), typed by a leading marker: 🔘 pressable (with component JSX tag, label, testID, onPress hint), 📝 text, 🖼 image (with src/alt). Elements covered by an open overlay are grouped under 🚫 Blocked — visible for context, but taps will NOT reach them until the overlay closes. Long text truncates to 80 chars (fullText=true for full strings); pressablesOnly=true returns just the lean tappable list. WHEN TO USE: After every tap/swipe that may navigate, and to read screen content (prices, labels, which image loaded) without a screenshot+OCR round-trip. LIMITATIONS: route is null without React Navigation / Expo Router. Requires a live Metro connection. Coordinates in points (iOS) / dp (Android); text frames are container-level (climb to nearest measurable host). SOURCE: this lists what is on screen, not where it lives in code — for the file:line that renders an element, call inspect_at_point(x, y). SEE ALSO: get_screen_layout for the full hierarchical component tree (deep inspection) — this gives a flat, tap-ready content list instead.
inspect_componentInspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_screen_layout or find_components to identify which component to inspect. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go. [PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings] PURPOSE: Reveal a mounted component's live props, hook state, and (optionally) child subtree so you can reason about why it renders the way it does. WHEN TO USE: User asks "why is this button disabled", "what props does X receive", or you need to confirm state changed after a tap. WORKFLOW: get_screen_layout or find_components -> inspect_component(componentName="Foo") -> tap or execute_in_app to change state -> inspect_component again. LIMITATIONS: Requires the component to be currently mounted in the fiber tree. Name matching is exact; use find_components for fuzzy/regex lookup. GOOD: inspect_component({ componentName: "SneakerCard", index: 0 }) BAD: inspect_component({ componentName: "Card" }) when many Card instances exist — pass index or narrow via find_components.
find_componentsFind components matching a name pattern. **TARGETED SEARCH**: Use after get_screen_layout or get_component_tree(structureOnly=true) to find specific components by pattern. Use includeLayout=true to get padding/margin/flex styles. [PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings] PURPOSE: Fast regex search over the entire fiber tree — including off-screen and wrapper components — to locate every instance of a component by name. WHEN TO USE: You know roughly what the component is called (e.g., "Button", "Screen$") but not where it lives, or you need counts/paths before drilling in with inspect_component. WORKFLOW: get_screen_layout (orient) -> find_components(pattern="...") -> inspect_component(componentName="...", index=N). LIMITATIONS: Matches the React display name only; minified builds may return opaque names. Large result sets — use maxResults or a tighter pattern. GOOD: find_components({ pattern: "Button" }); find_components({ pattern: "Screen$" }) BAD: find_components({ pattern: ".*" }) — floods the response; narrow the regex. SOURCE: searching by name to find a file? If you can point at it on screen, inspect_at_point(x, y) returns the file and line directly.
inspect_at_pointInspect layout AND props at (x, y). Returns FRAME PER ANCESTOR (position/size in dp for every ancestor that hit-tested the point) + the innermost component's PROPS (handlers as [Function], refs, custom props like onPress/data/testID). Pure JS hit-test via fiber + measureInWindow — no overlay toggled, zero visual side effect. Works on Paper and Fabric. PURPOSE: Layout/props diagnosis — "where is each ancestor positioned, and what props does the touched component expose?" WHEN TO USE: A button is clipped, hit area is wrong, animated frame is unexpected — or you need handler/ref/non-style props. Also preferred for tight loops (no overlay flicker). WORKFLOW: screenshot → suspect pixel → divide by pixel ratio → inspect_at_point(x, y). LIMITATIONS: Coordinates MUST be in dp, not screenshot pixels — wrong unit = wrong node. Style is the node's own style object, not the merged cascade. SOURCE: also returns `source: {file, line, column}` for the component at the point, plus the owner chain as `Source ancestors` (set source=false to skip in tight loops).
measureGet on-screen geometry {x, y, width, height} for a named React component instance. Calls measureInWindow on the matched fiber (or its nearest host descendant for composite components). Coordinates are in points (iOS) / dp (Android), same space as get_screen_layout and inspect_at_point. PURPOSE: One-shot, name-based component measurement — avoids hand-rolling fiber walks and Promise-wrapping measureInWindow callbacks in execute_in_app. WHEN TO USE: You already know the component's display name (from get_screen_layout or find_components) and just need its current bounds — e.g. to verify a layout change, compute a tap target, or compare against design specs. WORKFLOW: find_components(pattern="...") -> measure(componentName="...", index=N) -> tap(x, y) at the center, or inspect_at_point at the center to verify identity. LIMITATIONS: Returns post-layout on-screen geometry only — for static style use find_components({ includeLayout: true }). For point-based lookup use inspect_at_point. Off-screen fibers may return zeros; that's the truth, not an error. Composites with multiple host descendants return the first host descendant's bounds. GOOD: measure({ componentName: "SneakerCard", index: 0 }) BAD: measure({ componentName: "View" }) — too generic; narrow with find_components first. SEE ALSO: inspect_at_point for point-based variant; find_components({ includeLayout: true }) for static style.
Configuration
EXECBRO_API_URLOverride the license/account API base URL. Defaults to the production endpoint.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableigorzheludkov/execbro is public and reachablegithub.com/igorzheludkov/execbro ↗Pass
- Package names this repository as its sourceexecbro names igorzheludkov/execbro as sourcenpmjs.com/package/execbro ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for execbronpmjs.com/package/execbro/v/2.1.1#provenance ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-15github.com/igorzheludkov/execbro ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from execbroPass
- No critical advisory in the package or its dependencies144 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model58 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelleddelete_account has no destructiveHintFinding
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubExecBro
Catches what reading the code misses. ExecBro connects your AI coding agent to your running React Native app, so it can check stored data, network traffic and the real screen before it edits, and try the fix on the device before it says it's done.
On bugs where the code points to the wrong fix, Claude Sonnet 5.5 passed 14 of 18 runs with ExecBro and 9 of 18 without; Claude Opus 5.5 passed 18 of 18 with ExecBro and 16 of 18 without. Where the code alone explains the bug, both sides find it and ExecBro costs more. See the benchmark.
ExecBro is the runtime bridge between your AI coding assistant and your running React Native app — exposing MCP tools to read logs and network, inspect component state, capture screenshots, tap the UI, and run JS. Zero config, no SDK or code changes required to start — and installing the optional SDK is recommended for the most robust log and network capture.
Get started
- Setup ExecBro as an MCP server for your agent of choice
- Setup UI automation helpers
- Install the SDK in your React Native app — optional, but recommended for the most robust log, network, and state experience
- Authorize and link to the web dashboard — optional, for usage stats and session history
- Start your React Native app (
npm start/expo start) - Ask your AI assistant in plain language — e.g. "Connect to the simulator and investigate what caused the error on the screen"
See your usage — execbro.com
Log in at execbro.com to see your ExecBro activity rendered back to you: which tools you use most, tool error rates, and your session history — so you can spot flaky tools, track usage over time, and understand how your agent drives the app across sessions. It's built from the same anonymous telemetry described in Telemetry & Privacy, tied to your installation ID.
Linking is only for the dashboard: it attaches your installs to your account so the stats are yours. Nothing in the tooling is gated behind it.
Features
Runtime Interaction
- Console Log Capture - Capture
console.log,warn,error,info,debugwith filtering and search. Note: on a cold start (first app launch), logs emitted before the MCP server connects are missed — subsequent reloads capture everything. Install the optional SDK to buffer logs from the very first line of app startup - Network Request Tracking - Monitor HTTP requests/responses with headers, timing, and body content. Like logs, early network requests on cold start may be missed before the connection is established. Install the optional SDK for full capture from app startup including request/response bodies
- Response Mocking - Replace or tamper with HTTP responses so error paths are reached through the app's real code — the request builder, the error branch, the retry — instead of being faked by writing state directly. Simulate offline, delay responses, fail only the first attempt to test a retry, or re-issue a captured request with one field changed. Rules survive reload, and altered traffic is always tagged. See the mocking tutorial
- 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. Wire stores and other app internals straight into the agent with the optional SDK for direct, reliable state access
- Bundle Error Detection - Get Metro bundler errors and compilation issues with file locations
- Tap-to-Source - Point at any element with RN's Element Inspector and get back the absolute source file and line where it is rendered, resolved from the React fiber's
_debugStackvia Metro symbolication. Works on React 19, where_debugSourceno longer exists. Selections are buffered in the background, so taps you make during a manual inspector session are captured without asking the agent first
Device Control
- iOS Simulator - Screenshots, app management, URL handling, boot/terminate (via simctl)
- Android Devices - Screenshots, app install/launch, package management (via ADB)
- Unified Tap - Single
taptool with automatic fallback chain: fiber tree → accessibility → OCR → coordinates. Auto-detects platform, accepts coordinates from screenshots and layout tools unchanged. Returns post-tap screenshot and verifies visual change by default - Unified Swipe - Single
swipetool that auto-routes to iOS or Android based on the connected device. Takes coordinates in the same screen space as the layout tools and screenshots — no conversion — and returns averification.meaningfulsignal so agents detect end-of-list, non-scrollable surfaces, and missed coordinates — and on a screen with no React Native connection it says it could not inspect rather than guessing. Essential for scrolling virtualized lists (FlatList/SectionList) where off-screen items aren't in the fiber tree - Real Multi-Touch Pinch (Android emulator only — iOS in progress) - A
pinchtool that sends two genuine kernel touch contacts through the Android emulator's multi-touch bridge, so it zooms maps, galleries, WebViews, and native views alike — it works below the app, not through React Native. Returns the sameverification.meaningfulsignal asswipe, and refuses on unsupported targets instead of faking a result - UI Automation - Swipe, long press (
tapwithduration, resolving the target by testID/text/component), key events, and text input on both platforms.input_texttargets a field itself and verifies the write by reading it back; on Bridgeless/Fabric appsreplace:trueoverwrites pre-filled values by updating React state throughonChangeText, so controlled components (Formik, react-hook-form, useState) stay consistent.native:truetypes into whatever the OS reports as focused, with no RN connection needed, anddismiss_keyboardoperates the same way - Accessibility Inspection - Query UI hierarchy to find elements by text, label, or resource ID
- OCR Text Extraction - Extract visible text with tap-ready coordinates via Google Cloud Vision (works on any screen content)
Credential Safety
- Secrets never enter the transcript - Every tool's output passes one redaction chokepoint, so a token is replaced by a handle (
[secret:auth_api.acme.io]) whether it appears in a network header, a Redux store, a log line or a URL. Credential headers are matched by pattern rather than a fixed list, so vendor-namespaced ones (x-shopify-access-token,x-goog-api-key,x-hasura-admin-secret) are covered too, whilex-request-idandx-idempotency-keyare deliberately left alone. There is no per-call escape:EXECBRO_REDACT=offis set by a human and needs a restart - Use a credential without reading it -
list_secretsnames the handles;http_request({auth:{secret:"api.acme.io"}})substitutes the value host-side and issues the request from your machine — asAuthorization: Bearerby default, or in a key header or another scheme, so a credential never has to be pasted in to cover an unsupported shape, andvault_capturereads a token out of the app straight into the vault when no captured request revealed one. Each credential is bound to the origin it was observed on and refused elsewhere; the vault is memory-only - Server- vs client-side, isolated -
http_requestruns from the host with none of the app's TLS trust, proxy, cookie jar or mock rules;app_requestruns inside the app with all of them. Comparing the two is how you tell a backend bug from a client one — and a 401 from the host where the app succeeds is itself the answer that the backend enforces attestation - App data is treated as data - The server tells every connecting agent that logs, payloads, component trees and eval results are shaped by whatever the app talked to, and are never to be followed as instructions
Multi-Device Debugging
- Connect All Devices -
scan_metroautomatically discovers and connects to all Bridgeless targets on each Metro port - Device Targeting - Every tool accepts an optional
deviceparameter for targeting specific devices by name (case-insensitive substring match) - Per-Device Buffers - Logs and network requests are captured separately per device for clean debugging
- Cross-Platform Comparison - Debug iOS and Android side-by-side, comparing logs, network traffic, and component trees
Electron & Chromium (experimental)
-
Desktop React apps over CDP - An Electron window or a Chrome tab connects as a
chromiumtarget alongside your simulators, and every tool takes the samedeviceargument -
What works today - Console logs, network capture, replay and mocking (
network_mock,network_condition),execute_in_app, debug globals, Redux,http_request/app_request, React component inspection (get_component_tree,find_components,inspect_component), including on Vite apps whose DevTools hook has no renderers, plusscreenshot,tap,input_text,swipe(mouse-wheel scroll, and a real drag with four coordinates) andpress_key(Enter, Escape, Tab, arrows, shortcuts). JavaScript dialogs (alert/confirm/prompt/beforeunload) are reported by the tool that opened them instead of timing out, page tools refuse while one is open, andhandle_dialogaccepts or dismisses it. Taps find elements bydata-testid/id, visible text or React component name and click with real CDP mouse events. Screen reading without a screenshot:get_screen_state(tap-ready elements, what an overlay blocks),get_screen_layout,inspect_at_pointandmeasure -
Not yet -
pinch,navigateand the other mobile-only tools refuse a chromium target with a message saying so, rather than acting on the wrong device. Native HTML5 drag and drop (draggable) and hover are not handled yet -
Zero-config start -
electron_launch_app({ projectPath: "path/to/app" })starts an Electron project from its source folder with the debugging port open and connects its windows. It runs your project's ownelectronorelectron-vite, never a packaged build -
Or opt in - Add one dev-only line to the Electron main process, then run
scan_metro. Port 9222 is listed but not auto-connected, because connecting injects a network interceptor into the page. Attach withconnect_metro({ port: 9222, device: "<window title>" }), or setEXECBRO_CHROMIUM_PORTS=9222to auto-connectif (!app.isPackaged) app.commandLine.appendSwitch('remote-debugging-port', '9222')Keep the
!app.isPackagedguard: an open debugging port on a packaged build lets anything that can reach it run code in your renderer
Native Android (preview)
- Kotlin apps without a JavaScript runtime - A native app that includes
execbro-sdk-androidin its debug build registers named state and commands.scan_metrofinds it over adb,list_debug_globalsandinspect_globalread its state,run_app_commandruns its commands,navigatedrives Jetpack Navigation, andscreenshotcaptures the screen - Coming soon - The SDK is not published to Maven yet. Execbro already supports it; install instructions will follow with the SDK release
Under the Hood
- Auto-Discovery - Scans Metro on ports 8081-8090 automatically, and lists Chromium/Electron targets on 9222 (plus any ports in
EXECBRO_CHROMIUM_PORTS) - Multi-Device Support - Connects to all Bridgeless targets simultaneously, with per-device log and network buffers
- Auto-Reconnection - Exponential backoff (up to 8 attempts) when connection drops
- Efficient Buffering - Circular buffers: 500 logs, 200 network requests, 100 inspector selections
- Platform Support - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)
Setup
Add ExecBro to Claude Code in one command — no installation, npx fetches the latest version on demand:
claude mcp add execbro --scope project -- npx -y execbro@latest
Then fully restart the client (quit and relaunch) so it picks up the new server.
Project scope writes a .mcp.json you can commit, so the whole team picks ExecBro up in this repo and nowhere else. Swap project for user to register it globally instead — convenient if you work in React Native all day, but it starts ExecBro in every session you open, including repos with no Metro server to connect to.
Using a different client or need platform setup? The full setup guide covers Claude Desktop, Codex CLI, Cursor, VS Code Copilot, Windsurf, Zed, and Gemini CLI, plus Android and iOS simulator UI automation requirements.
Install the SDK (recommended)
ExecBro works with zero app changes, but installing the companion execbro-sdk package is the single biggest upgrade to debugging quality. It lets you wire up the important parts of your app — your state stores and your network layer — directly into the agent's reach, so the AI inspects real Redux/TanStack Query state and full request/response bodies instead of guessing from the outside.
| Without SDK | With SDK | |
|---|---|---|
| State stores (Redux, TanStack Query, …) | Manual via execute_in_app |
Wired up — direct references |
| Request/response bodies | Not available | Full (including GraphQL) |
| Startup network requests (auth, config) | Missed | Captured from first fetch |
| Console logs from startup | May miss early logs | Captured from first log |
| Works on Bridgeless (Expo SDK 52+) | Partial | Full |
It's one npm install plus a single init() call in your app's entry file. See the SDK guide for install, initialization, and every config option.
Requirements
- Node.js 20.9+
- React Native app running with Metro bundler
- Recommended:
execbro-sdkin your app — wires stores and the network layer into the agent for dramatically better debugging (optional; ExecBro works without it) - iOS UI automation: AXe CLI (
brew install cameroncooke/axe/axe, default) or Facebook IDB (brew install idb-companion, opt in viaIOS_DRIVER=idb) — required for tap, swipe, text input, accessibility on iOS Simulator - Optional for offline OCR fallback: Python 3.6+ (only needed when cloud OCR is unavailable, see OCR guide)
Claude Code Skills
Pre-built skills for common debugging workflows — session setup, log inspection, network debugging, and more. See the skills guide for the full list and installation instructions.
Available Tools
See the full tool reference for all tools with descriptions. Key tools:
| Tool | Description |
|---|---|
scan_metro |
Start here — scan for Metro servers and auto-connect |
get_logs / search_logs |
Capture and search console logs with filtering and summaries |
get_network_requests |
Monitor HTTP requests with method/status filtering |
get_timeline |
Actions, route changes, requests, logs and restarts in one time-ordered list |
get_screen_state |
Orientation snapshot — active route, overlays, and every element with a tap-ready (x, y) |
get_screen_layout |
Screen map of visible components with positions, sizes, and text content |
tap |
Unified tap — auto-detects platform, tries fiber → accessibility → OCR → coordinates |
pinch |
Real two-finger pinch-to-zoom — Android emulator only (iOS in progress) |
input_text |
Type text — targets and focuses a field itself, or native:true for whatever's focused. replace:true clears first (Fabric) |
dismiss_keyboard |
Blur the focused input and close the on-screen keyboard |
execute_in_app |
Run JS expressions in the app runtime (REPL-style) |
screenshot |
Take a screenshot on any platform: iOS simulator, Android, Electron or Chrome, and a USB-attached physical iPhone/iPad (capture only) |
Usage
-
Start your React Native app:
npm start # or expo start -
Just describe what you want in plain language — the agent picks the right tools. You don't need to know tool names or ask for a specific one. For example:
Connect to the simulator and investigate what caused the error on the screenCheck the network logs and investigate why this error is happeningWhy is the current screen empty? Take a look and figure it outTap the "Sign in" button and tell me what happensThe list won't scroll — scroll it down and check what's going onWhy does this button look wrong — what component renders it and where?The agent connects to Metro, reads logs and network, inspects the screen, and drives the UI as needed to answer.
Detailed Guides
| Guide | Description |
|---|---|
| Setup | Per-client MCP config (Claude, Codex, Cursor, VS Code, …), Android & iOS setup |
| SDK Setup | Install & init() the in-app SDK to wire stores + network layer into the agent |
| Console Logging | get_logs parameters, filtering, summary mode, token optimization |
| Network Tracking | SDK setup for full capture, filtering, request details, statistics |
| Network Mocking | Tutorial: force a 500, drop a field, test a retry, go offline, replay a request |
| App Inspection | Debug globals (Apollo, Redux, Expo Router), execute_in_app, limitations |
| Layout & Component Inspection | get_screen_layout, component tree, inspect_at_point, find_components |
| Device Interaction | Unified tap, platform-specific gestures, text input, key events |
| OCR Text Extraction | Cloud Vision OCR inside tap, offline fallback, language config |
| Claude Code Skills | Pre-built skills for session setup, debugging, and automation |
| Full Tool Reference | Complete list of all 62 tools with descriptions |
How It Works
- Fetches device list from Metro's
/jsonendpoint - Connects to the main JS runtime via CDP (Chrome DevTools Protocol) WebSocket
- Enables
Runtime.enableto receiveRuntime.consoleAPICalledevents - Network capture via two paths:
- With SDK: Reads from the SDK's in-app buffer via
Runtime.evaluate— captures all requests from startup with full headers and bodies, including cold-start events that CDP would miss - Without SDK: Enables CDP
Network.enable(on supported targets) or injects a JS fetch interceptor as fallback. On cold start, events emitted before the CDP connection is established are lost; subsequent reloads capture everything
- With SDK: Reads from the SDK's in-app buffer via
- Response mocking runs in that same injected interceptor: rules are matched before the request reaches the wire, and are re-pushed to every new JS context so they survive a reload
- Stores logs and network requests in circular buffers for retrieval
Connection Management
- One server per session — each agent session (each terminal or IDE window) runs its own ExecBro MCP server instance.
- Connects on request, not on startup — the server never auto-connects. It only attaches to your running React Native app when you ask it to (e.g.
scan_metro), so it stays out of the way until you actually need a device. - One driver per device — if two or more sessions in the same project point at the same Metro/device, they'll compete to control it, like a car with two steering wheels. Keep interaction to a single session per device.
- Want parallel sessions? Give each its own device + port — run separate work in a git worktree with its own Metro instance on a different port, and connect a second device (simulator/emulator) to it. For example, keep
mainon the default8081and start the worktree's Metro on8082(npx react-native start --port 8082, ornpx expo start --port 8082), then launch that worktree's app pointed at8082. Each agent session thenscan_metros and drives its own device, so the two never fight over the connection.
Troubleshooting
No devices found
- Make sure the app is running on a simulator/device
- Check that Metro bundler is running (
npm start)
Logs not appearing
- Ensure the app is actively running (not just Metro)
- Try
clear_logsthen trigger some actions in the app - Check
get_appsto verify connection status - On cold start (first launch): The CDP connection is established after the app's early initialization code has already run, so startup logs and network requests are missed. Once connected, use
reload_app— the subsequent reload captures everything from the beginning because the connection is already in place. To capture startup events on every launch, install the optional SDK
ExecBro MCP questions
How do I add ExecBro MCP to Claude Code?
Run claude mcp add execbro-859fd2 -- npx -y execbro in your terminal. Add --scope user to make it available in every project.
How do I add ExecBro MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does ExecBro MCP provide?
It exposes 58 tools, including activate_license, delete_account, get_usage_guide, get_license_status, send_feedback.
Does ExecBro require changes to my React Native code?
No, it works with zero config and no SDK or code changes required to start, though installing the optional SDK is recommended for better log and network capture.
Can I use ExecBro to test error paths in my app?
Yes, you can use response mocking to replace or tamper with HTTP responses to reach error paths through the app's real code.
How does ExecBro handle sensitive credentials in logs?
Every tool's output passes through a redaction chokepoint where tokens are replaced by handles to ensure secrets never enter the transcript.
Does it support desktop applications?
Yes, it has experimental support for Electron and Chromium targets, allowing you to inspect console logs, network, and perform UI automation on desktop React apps.