ProductIntegrationsPricingFAQDocsBlogFeedback

Get started

Run one command — npx @ceraph/react-native-mcp@latest init — to wire up your MCP client, then bring your app up on a device or simulator when you need to.

A note on the commands below

We write ceraph <command> throughout these docs. init sets up the global ceraph command automatically, so these work as written. If the global install couldn't run — for example on a permissions-restricted machine — prefix any of them with npx @ceraph/react-native-mcp@latest instead (e.g. npx @ceraph/react-native-mcp@latest start).

Before you start

You need the following on your machine:

  • A Mac with Xcode (Command Line Tools installed). The runtime path is Apple-specific, so Ceraph does not run on Linux or Windows.
  • Either a real iOS device (iOS 16+) connected over USB and unlocked, or a booted iOS Simulator (windowed or headless). Ceraph auto-detects: it uses a connected device if one is present, otherwise the simulator.
  • Node.js 18+.
  • An Expo dev client or a prebuilt app. Expo Go is not supported.

Ceraph is iOS-only today; Android is on the roadmap. It works with Expo (Expo Router) and bare React Native (React Navigation).

1. Set up — run once per project

From your React Native project root, run init:

npx @ceraph/react-native-mcp@latest init

@latest pins the newest published package on every run, so there is no separate global install to do first. This one-time step:

  • Configures every MCP client it detects — Claude Code, Cursor, Codex, VS Code, Windsurf, and Antigravity (Cline, Roo Code, and JetBrains IDEs can be set up manually).
  • Sets up the ceraph command on your PATH automatically — a heads-up log line, no prompt — so you can run ceraph start directly. It is skipped for agents, CI, and other non-interactive runs, and degrades gracefully if the machine blocks a global install (use the npx fallback from the note above).
  • Installs a Claude Code hook that injects runtime errors into your conversation automatically.
  • Adds .rn-errors.json to your .gitignore.
  • Signs you in (browser OAuth) so Pro features like test-user provisioning can reach the Ceraph server.

2. Bring the app up — each session

Setup alone does not get you testing — you still need to bring the app up. Run ceraph start:

ceraph start

One call reaches a ready-to-test state: it starts Metro, builds and installs the app, starts WebDriverAgent, and verifies on-device automation. It runs only what is missing and stops at the first failed gate with a concrete fix.

start defaults to auto — it prefers a connected iPhone and falls back to a booted simulator. Pin a target with a flag when you need one: --device, --simulator, or --headless (a simulator with no Simulator.app window).

You often don't need to run start yourself

Your coding agent can start Ceraph on its own — it calls the same bring-up through the MCP. On the simulator, or any time the agent is driving, skip the manual ceraph start and just ask your agent to test what you changed.

The guided ceraph start is mainly for hands-on device bring-up — the moments that need a human, like unlocking the phone or entering a passcode.

3. Ask your agent to test

With the app up, drive it from your editor. Edit code — add a screen, fix a bug, tweak a form — then ask your agent to test what the change touched. It drives the connected device or simulator, observes each screen through a structured accessibility snapshot, acts with the screen primitives (tap, type, swipe, deep-link, screenshot), reads any runtime errors, and reports what passed and what looks off.

Full tool reference — every MCP tool, environment variable, and the camera / hooks setup — lives in the README: @ceraph/react-native-mcp on npm.