rn-mcp

# rn-mcp MCP server that lets Claude Code automate iOS simulators for React Native / Expo development — take screenshots, read Metro logs, tap UI elements by selector, record and replay flows. **macOS only. Requires Xcode + iOS Simulator.** ## Install ```bash npm install -g github:Bernecian/rn-mcp claude mcp add rn-mcp --scope user -- rn-mcp ``` Restart Claude Code after adding. ## Requirements | Feature | Requirement | |---------|-------------| | Screenshots, logs, URLs | Xcode (ships with macOS dev tools) | | Tap / swipe / UI automation | [idb](https://fbidb.io) | ### Install idb (for automation tools) ```bash brew tap facebook/fb brew install idb-companion pip3 install fb-idb ``` ## Tools ### Default (always available) | Tool | What it does | |------|--------------| | `screenshot` | PNG screenshot of the booted simulator | | `read_logs` | Stream Metro / JS logs live from the simulator | | `reload_app` | Hot-reload via Metro | | `restart_app` | Kill and relaunch the app process | | `open_url` | Open a deep link or web URL in the simulator | | `app_status` | Check if Metro and the simulator are running | | `bundle_status` | Check Metro bundle health | | `run_plan` | Run a saved plan (tap/swipe/assert steps by selector) | | `list_plans` | List saved plans | | `run_flow` | Replay a saved legacy flow | | `list_flows` | List saved flows | ### Advanced (set `RN_MCP_ADVANCED=1`) Raw automation tools are hidden by default to keep agents from reaching for footguns. Set `RN_MCP_ADVANCED=1` in the MCP server environment to unlock: `act`, `automation_tap`, `automation_swipe`, `automation_type`, `automation_key`, `describe_ui`, `inspect_region`, `inspect_node`, `boot_simulator`, `list_simulators`, `save_flow`, `clear_recording` ## Usage Boot a simulator, start Metro, then ask Claude: - "Take a screenshot" - "Read the last 50 lines of Metro logs" - "Tap the Login button" - "Run the plan called onboarding" ### Plans Plans are selector-based sequences stored in `rn-mcp.plans.json`. Any element with a React Native `testID` prop (maps to iOS `accessibilityIdentifier`) is addressable by selector. ```json { "plans": { "go-to-profile": [ { "action": "tap", "selector": "tab-profile" }, { "action": "assert", "selector": "profile-screen" } ] } } ``` Plans file is resolved in this order: 1. `RN_MCP_PLANS_PATH` env — explicit override 2. `cwd/rn-mcp.plans.json` — project-local file 3. Package root `rn-mcp.plans.json` — bundled default ## Environment variables | Variable | Default | Description | |----------|---------|-------------| | `RN_MCP_METRO_URL` | `http://localhost:8081` | Metro base URL | | `RN_MCP_PLANS_PATH` | (auto-resolved) | Path to plans JSON | | `RN_MCP_FLOWS_PATH` | `./rn-mcp.flows.json` | Path to legacy flows JSON | | `RN_MCP_SESSION_LOG` | `./.rn-mcp/session.log.jsonl` | JSONL session log path | | `RN_MCP_ADVANCED` | — | Set to `1` to unlock advanced tools | ## Observability Every tool call is appended to `.rn-mcp/session.log.jsonl`: ```bash tail -f .rn-mcp/session.log.jsonl ``` Each line: `{ ts, tool, args, durationMs, status: "ok"|"error", note }` ## Architecture ``` src/ ├── index.ts MCP server + tool registry + session log ├── types.ts ToolDef, ToolResult ├── utils.ts simctl / idb helpers, screenshot, matchNode ├── flows.ts legacy flow storage + runner ├── plans.ts plan storage: selector-based PlanStep[] ├── recording.ts in-memory recording buffer └── tools/ ├── screenshot.ts ├── logs.ts ├── reload.ts ├── restart.ts ├── simulator.ts open_url, list/boot ├── status.ts app_status, bundle_status ├── automation.ts tap (coords), swipe, type, key, describe_ui ├── act.ts single-action + auto-record ├── run_plan.ts batch executor with selector polling ├── list_plans.ts ├── save_flow.ts save recording → plans + flows ├── flow.ts run_flow / list_flows └── inspect.ts inspect_region, inspect_node ``` ## License MIT