ProductIntegrationsPricingFAQFeedbackX

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:

  • For iOS, a Mac with Xcode (Command Line Tools installed) and either an unlocked iOS 16+ USB device or a booted iOS Simulator.
  • For Android on macOS, Windows, or Linux, the Android SDK/JDK used by your project with adb available, plus either an authorized USB device or a booted Android Emulator.
  • Node.js 20.19+, 22.12+, or 24+.
  • An Expo dev client or a prebuilt app. Expo Go is not supported.

Ceraph supports both Expo and bare React Native projects on iOS and Android.

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, 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 runtime-error delivery for Claude Code, Cursor, Codex, VS Code, and Antigravity, with client-independent MCP notifications and rn_get_errors available everywhere.
  • Configures Expo Router compatibility while preserving existing intent customizations.
  • Adds .rn-errors.json to your .gitignore.
  • Signs you in through browser OAuth when you choose Pro; Starter requires no account.

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 on iOS or UiAutomator2 on Android, 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. macOS defaults ambiguous requests to iOS; Windows and Linux default them to Android. Pin a target with --device, --simulator, --headless, --emulator, or --no-window. Add --ios or --android when you want to choose the platform explicitly.

Run start yourself when timing matters

Your coding agent can start Ceraph on its own — it calls the same bring-up through the MCP, so you can usually just ask it to test what you changed. Manual ceraph start works with every target.

It is especially useful for priming a physical device ahead of testing: run it while your agent is still implementing, unlock the phone and complete any passcode or trust prompts, then step away knowing Ceraph will be ready when verification begins.

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.