@ceraph/react-native-mcp

@ceraph/react-native-mcp

MCP server for React Native and Expo development. It lets your coding agent drive and test your app end-to-end on both iOS and Android. Supports real devices and simulators/emulators.

Works with any MCP client: Claude Code, Cursor, Codex, VS Code, Antigravity, and others.

To install and configure Ceraph, run this command from your project root:

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

Platform support

Ceraph supports React Native and Expo apps. iOS testing runs on macOS through Xcode and WebDriverAgent. Android testing runs on macOS, Windows, or Linux through ADB and UiAutomator2. Expo projects use a development build rather than Expo Go.

Target / host	Status	Notes
iOS device	Supported	macOS only. WebDriverAgent installs through Xcode once, then Ceraph manages subsequent starts.
iOS Simulator	Supported	macOS only. Windowed and headless targets are supported; Ceraph builds and launches simulator WDA automatically.
Android device	Supported	macOS, Windows, or Linux. Enable USB debugging and authorize the host when prompted.
Android Emulator	Supported	macOS, Windows, or Linux. Windowed and no-window modes are supported; Ceraph manages Appium/UiAutomator2.

Choosing a platform and target

On macOS, ceraph start defaults to iOS. On Windows and Linux it defaults to Android. An active automation session stays selected. With --device, Ceraph selects the platform automatically when exactly one USB device is connected. When multiple devices are connected, pass the exact Apple UDID/CoreDevice identifier or Android adb serial; the identifier also identifies the platform. Exact identifiers remain USB-only unless you also pass --wifi.

ceraph start [--ios|--android] [--device|--simulator|--headless|--emulator|--no-window] [id]

Platform	Physical device	Windowed virtual runtime	Background virtual runtime
iOS	--device	--simulator	--headless
Android	--device	--emulator	--no-window

The platform flag is usually unnecessary because physical devices have unique identifiers and virtual-runtime targets imply their platform. For the ordinary single-device setup, run ceraph start --device. Add an exact Apple UDID or Android adb serial when you need to choose among multiple USB-connected devices. To target a specific paired device over Wi-Fi, run ceraph start --device <UDID-or-adb-serial> --wifi. Run ceraph start --no-wifi to revoke Wi-Fi access for this project's active Ceraph session. Approval lasts until the session ends or you revoke it.

The rn_target_status tool reports the active platform, exact runtime, target presentation, and automation readiness.

Requirements

• Node.js 20.19+, 22.12+, or 24+
• For iOS: macOS with Xcode 14+ and either an iOS 16+ USB device or an available Simulator runtime. See iOS setup.
• For Android: the Android SDK/JDK used by your project, with adb available, and either an authorized USB device or a configured Android Emulator. See Android setup.

Multiple agents: One running app instance has one active Ceraph driver. Simultaneous contenders are arbitrated so they receive a busy result instead of fighting over the same device, simulator, or emulator.

iOS setup

Install Xcode 14 or later and complete its first-launch setup. Physical devices require iOS 16 or later; simulator testing requires an installed iOS Simulator runtime.

Physical device

Connect and unlock the device over USB, trust the Mac when prompted, and enable Developer Mode. Start the sole connected device with ceraph start --device. When multiple devices are connected, select it with ceraph start --device <UDID-or-CoreDevice-ID>.

WebDriverAgent installs through Xcode once. Ceraph then manages subsequent starts, including the USB connection to WDA, and routes supported interaction and lifecycle tools to the selected device. If the Mac needs an additional dependency, ceraph doctor provides the exact installation step.

Simulator

The Simulator has two presentation modes:

• ceraph start --simulator selects and boots a windowed Simulator for visible testing.
• ceraph start --headless runs without Simulator.app for CI, cloud Macs, and background agent verification. Screenshots, recordings, snapshots, and WDA remain available; host audio is not disabled.

Add an exact simulator UDID after either flag to select a particular simulator. For projects with multiple iOS build flavors, add --scheme <name> and --configuration <name> (default Debug).

Ceraph automatically installs the optional appium-webdriveragent package the first time it targets a Simulator, then builds and launches WDA. The first build usually takes about a minute; later runs reuse it. Device-only setups do not install this dependency.

Ceraph reuses an eligible booted Simulator or boots the selected/default one when needed. Use xcrun simctl list devices available to see available Simulators. Call rn_wda_stop to stop WDA, or exit the MCP server to stop its managed process.

To make headless mode the default for the current environment:

export CERAPH_TARGET=headless

An explicit target still overrides that preference for one run. The standalone rn_build_ios primitive supports headless builds only when you deliberately opt into its unmanaged mode.

Physical device and Simulator connected: An active Simulator automation session remains selected even when a phone is connected. Run ceraph start --device to select the phone instead. Before a Simulator session exists, automatic selection uses a USB-connected iPhone; a Wi-Fi-only iPhone is never selected automatically. Target one explicitly with ceraph start --device <UDID-or-CoreDevice-ID> --wifi.

Android setup

Install Android Studio and use its SDK Manager to install Platform-Tools and the SDK components required by your React Native project. Ensure adb is available on your PATH, then confirm that it can see the intended runtime:

adb devices -l

Physical device

Enable Developer options and USB debugging, connect and unlock the phone over USB, and accept the host authorization prompt. Start the sole connected device with ceraph start --device. When multiple devices are connected, select the phone with ceraph start --device <adb-serial>.

Emulator

The Android Emulator has two presentation modes:

• ceraph start --emulator selects or launches a windowed AVD.
• ceraph start --no-window runs an AVD without a window or host audio for CI and background testing.

Add an AVD name after either flag to select the virtual device to start or reuse. --emulator also accepts the adb serial of a running emulator. When the project has multiple debuggable build variants, add --variant <name>.

Ceraph manages build and installation, automation, app launch, wake and unlock verification, and Expo dev-client routing for both Android targets.

Physical device and Emulator connected: An active Emulator automation session remains selected even when a phone is connected. Run ceraph start --device to select the phone instead. Before an Emulator session exists, automatic selection uses a USB-connected Android phone; a Wi-Fi-only phone is never selected automatically. Target one explicitly with ceraph start --device <adb-serial> --wifi.

Quick start

Run one command from your project root:

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

init automatically:

• Configures supported MCP clients and runtime-error delivery
• Integrates with Expo and bare React Native projects while preserving existing project customizations
• Keeps generated local state out of version control
• Signs you in through browser OAuth when you choose Pro; Starter requires no account
• Makes the ceraph command available and follows your saved user-level MCP preference; first-time setup defaults to user-level access
• In interactive Git projects, offers to commit portable team setup; it never commits for agents, CI, or other non-interactive runs

init configures the project but does not start a runtime. Your coding agent can call ceraph_start itself. To prime a physical device or start Ceraph manually:

ceraph start

(No ceraph on your PATH — a permissions-restricted machine, --no-global, or a non-interactive init? Use npx @ceraph/react-native-mcp@latest start instead.)

start picks a platform and target automatically using the host defaults above. See Choosing a platform and target to select a different runtime or an exact device.

Using Ceraph across projects

User-level integrations make Ceraph available across projects in supported coding clients. When you request testing in a React Native app that has not been set up, the agent can initialize it before testing.

Diagnostics

ceraph start runs the same health checks automatically after bring-up. To inspect project and runtime readiness without building the app or starting Metro, run:

ceraph doctor

Doctor accepts the same target flags as start. Use ceraph doctor --json for automation or a GitHub issue, and ceraph doctor --help for the full command reference.

Account

Sign in or switch the Ceraph account used by every project on this machine:

ceraph login

Sign out without changing any project setup, hooks, fixtures, or preferences:

ceraph logout

Both commands use a machine-wide credential. Logout affects only this machine; it does not sign you out of the Ceraph website or other computers.

If the global ceraph command is not installed, use npx @ceraph/react-native-mcp@latest login or npx @ceraph/react-native-mcp@latest logout.

Other MCP clients

ceraph init configures the supported client integrations automatically. Use the instructions below only for clients Ceraph does not yet configure.

Cline / Roo Code (VS Code extensions)

Open VS Code Settings → Extensions → Cline (or Roo Code) → MCP Servers, then add:

{
  "react-native-mcp": {
    "command": "npx",
    "args": ["-y", "@ceraph/react-native-mcp@latest"]
  }
}

JetBrains IDEs

Settings → Tools → MCP Servers → Add, then enter:

• Name: react-native-mcp
• Command: npx
• Args: -y @ceraph/react-native-mcp@latest

Primary tools

Setup and preferences

Tool	Description
ceraph_init	Complete project setup, preserving existing choices and returning required decisions.
ceraph_init_status	Inspect project setup without starting an app.
ceraph_set_camera_test_media	Switch a running development app between registered camera test media and the real camera.
ceraph_add_camera_image	Register an image fixture for CeraphCamera and sync its development registry.
ceraph_add_camera_video	Register a video fixture for CeraphCamera and sync its development registry.
rn_sync_camera_registry	Sync manually added camera fixtures into the development registry.
ceraph_report_issue	Prepare a sanitized public defect report and submit only with per-report or account-bound lasting authorization.

Build & Runtime

Tool	Description
ceraph_start	Call this first. Bring the selected runtime to a ready-to-test state. Runs only what is missing and returns remediation for the first failed check.
ceraph_doctor	Diagnose project and runtime readiness without starting a test session. Returns structured failures with remediation.
rn_build_ios	Advanced unmanaged iOS build diagnostic. Prefer ceraph_start, or app_launch({ rebuild: true }) when automation is not needed.
rn_build_android	Advanced unmanaged Android build diagnostic. Prefer ceraph_start, or app_launch({ rebuild: true }) when automation is not needed.
rn_metro_start	Start or reuse Metro and capture console output.
rn_get_errors	Return captured build and runtime errors.
rn_get_console	Return recent app console output, optionally filtered by level.
rn_check_prebuild	Report whether an Expo native project needs a clean prebuild and why.
rn_stop	Stop processes managed by Ceraph for the current project.

Target & platform drivers

Tool	Description
rn_target_status	Report the active platform, exact runtime, presentation mode, and automation readiness.
rn_wait_for_device	Wait for the selected physical device to become available and ready.
rn_wda_start	Advanced: start or reuse automation for a booted iOS Simulator. Normal testing should begin with ceraph_start.
rn_wda_stop	Stop the iOS Simulator automation session started by rn_wda_start.

Screen Interaction

Tool	Description
ceraph_snapshot	Structured accessibility-tree snapshot of the current screen. Pass includeStyles: true after visual changes to include bounded render-time styles for uniquely matched visible elements, plus honest style-coverage metadata.
ceraph_run_hook	Run a project-owned command inside the live app when authentication, gated state, a development-only blocker, or cleanup would otherwise prevent meaningful testing.
ceraph_record_run	Replay an already-verified path without model pauses and produce a clean MP4 with structured UI snapshots and screenshots tracing the verified flow. The recording is screen-only evidence; it does not capture or verify audio.
screen_tap	Tap by snapshot ref, bounds, or coordinates. Prefer a stable ref; screenshot-derived coordinates are best-effort.
screen_tap_and_verify	Find an element by ref/text/label/type, tap its center, and assert a required follow-up selector is on screen. Use screen_tap when no postcondition is needed.
screen_tap_chain	Tap a sequence of controls on the same stable screen; sends nothing if any target cannot be resolved.
screen_type_into_field	Focus an input and type into it. Set clearFirst: true to clear the field first.
screen_swipe	Swipe up/down/left/right. Defaults to a 60%-of-axis swipe from screen center.
screen_scroll_to	Repeatedly swipe until a matching element is on screen (no tap).
screen_long_press	Long-press a matched element for a configurable duration.
screen_press_key	Press a hardware/system button: back, home, volumeUp, volumeDown, lock.
screen_open_url	Open a URL / deep link (e.g. myapp://product/42) to jump straight to a screen — useful for testing your app's deep-link routes.
screen_screenshot	Capture a pixel screenshot of the current screen (a viewable image block) — for confirming actual rendered appearance. For structured screen data (elements, roles, bounds, refs to act on) use ceraph_snapshot.
screen_wait_for	Poll until an element is on screen (or no longer on screen). Pass timeoutMs: 0 for a one-shot check.

App Lifecycle & Device

Tool	Description
app_launch	Open or relaunch an installed app. For the project app, Ceraph also makes its Metro bundle ready without starting automation; pass rebuild: true to rebuild and install it first.
app_terminate	Terminate an app by its iOS bundle ID or Android package ID.
app_activate	Bring an app to the foreground without a cold restart.
app_list_installed	List installed apps on the selected runtime.
app_info	Report the foreground app's identity and name. Android also reports its activity.
rn_reload	Reload the app's JS bundle, wait for it to come back, then capture a screenshot. Requires installCeraph active in the app; dev-only.
device_ensure_awake	Ensure the device is awake and unlocked. Returns structured remediation when locked.
device_set_orientation	Request portrait or landscape and verify the rotation reached both the device and foreground app.
ceraph_add_media	Add an image or video to the selected runtime's system photo library so the agent can test the app's real native media picker. Supports iOS simulators plus Android emulators and devices.

Driving the app

Ceraph provides two building blocks for reliable app driving:

• ceraph_snapshot returns structured screen elements, roles, values, bounds, and stable refs. Call it before acting and again after each action.
• The screen_* and app_* tools act on those refs, navigate, type, capture screenshots, and manage the app on the selected runtime.

The loop is ceraph_start → ceraph_snapshot → act → snapshot again. Once a path works, ceraph_record_run can replay it into an MP4 and ordered state trace for review. For a settled static change, use screen_screenshot plus ceraph_snapshot instead.

License notice: The Ceraph Software License Agreement strictly prohibits using Ceraph software, documentation, machine-readable tool descriptions, or other technical materials as a blueprint to reproduce, emulate, reimplement, or otherwise create Ceraph features for any purpose, including personal or internal use. Read the full agreement.

Media picker testing

Call ceraph_add_media before opening a native image or video picker when the selected runtime needs something to choose. Ceraph adds the supplied media to the runtime's system photo library; the agent then opens and drives the app's real picker UI as part of the flow.

The tool accepts JPEG, PNG, WebP, and HEIC images up to 5 MB, plus MP4, MOV, and M4V videos up to 25 MB. It supports iOS Simulators and Android emulators or devices. Physical iPhones cannot be seeded through this interface, so Ceraph returns targeted remediation. Added media remains until it is deleted; erasing a simulator or emulator also removes its media.

Camera testing

Ceraph makes camera-dependent flows deterministic in development builds. Each <CeraphCamera mediaKey> can return a configured image from takePictureAsync and a configured video from recordAsync, while production builds continue to use the real camera.

Setup

Run ceraph init; it configures the development integration and offers to replace detected Expo CameraView components.

Assign a descriptive key to each camera scenario:

import { CeraphCamera } from "@ceraph/react-native-mcp/shim";

export function ScanProfileScreen() {
  return <CeraphCamera mediaKey="profile" style={{ flex: 1 }} facing="front" ref={cameraRef} />;
}

CeraphCamera accepts the same camera props used by Expo Camera. The same mediaKey can select both an image and a video for a screen that supports both capture modes.

Ask your agent to add test images or videos. Images support JPEG, PNG, WebP, and HEIC up to 5 MB; videos support MP4, MOV, and M4V up to 25 MB. Set overwrite: true when replacing an existing key.

For manual fixture management, use lowercase, hyphenated filenames whose stem matches mediaKey:

.ceraph/camera-images/profile.jpg
.ceraph/camera-videos/treadmill.mp4

Run ceraph doctor after adding files manually so they are ready for the next development bundle. If a media key has no matching image fixture, development capture uses Ceraph's built-in placeholder; video capture continues through the real recorder.

Your agent can switch a running development app between registered test media and the real camera with ceraph_set_camera_test_media, without rebuilding. The choice stays enabled between actions while connected. Physical devices use the real camera by default; simulators and emulators default to test media. Set CERAPH_CAMERA_TEST_MEDIA=on, off, or auto for a process override, or ask your agent to save the cameraTestMedia preference. A fixed on or off override takes precedence over runtime switching; use auto to leave runtime switching available. These choices never enable fixtures in production builds.

Production safety

Camera fixtures and test behavior are development-only. Production builds use the real camera and exclude configured test media.

Hooks

A hook is a project-owned command that Ceraph can run inside the live development app. It can use the app's own state, navigation, auth, feature-flag, and API modules. The agent invokes a hook explicitly with ceraph_run_hook.

Create a hook in .ceraph/hooks/, one file per route, named *.hook.ts or *.hook.js. It exports the route it fires on and a run function, and may import your app's own modules:

// .ceraph/hooks/paywall.hook.ts
import { grantTestEntitlement } from "../../src/services/devTesting";
import { getCurrentPath } from "../../src/navigation";

export const route = "/paywall";
export const description = "Grant disposable premium access for this test run";
export const isAvailable = () => getCurrentPath() === "/paywall";

export async function run(ctx) {
  await grantTestEntitlement({ runId: ctx.runId });
  return { ok: true };
}

Restart Metro after adding or removing a hook. Available routes and descriptions appear in ceraph_snapshot.meta.availableHooks; invoke one with ceraph_run_hook({ route: "/paywall" }).

Hook exports and the run(ctx) contract

• export const route (required) — the route name presented to the agent, as a string literal.
• export const description (optional) — a short explanation surfaced beside the route so the agent knows what state the hook establishes.
• export const isAvailable (optional) — a fast, side-effect-free predicate that controls whether the hook is advertised.

isAvailable controls discovery, not authorization. Every registered route can still be invoked directly, so hooks must enforce any required checks themselves.

run may be synchronous or asynchronous and returns { ok, error? }:

ctx field	Meaning
ctx.route	The registered hook route the agent chose to invoke.
ctx.runId	Stable identifier of the current run.

Return { ok: true } once setup is complete, or { ok: false, error: "…" } to explain why it failed. Thrown errors are also recorded as failures.

Hooks are development-only and are excluded from production builds.

Preferences

Personal preferences are saved in ~/.ceraph/preferences.json and apply across projects on this machine. Ask your agent to remember a choice; restart Ceraph to apply saved changes.

Testing

Preference	Default	Purpose
windowFocus	true	Bring simulator or emulator windows to the foreground. Use ceraph start --focus or --no-focus for one run.
cameraTestMedia	auto	Use registered camera media on simulators/emulators and the real camera on physical devices. See Camera testing.
keepAwake	true	Keep physical devices awake during testing.
fastReload	true	Reconnect development builds after Metro restarts, network changes, or the host resumes from sleep. Reloads reset in-memory state; native changes still require a rebuild.

For keep-awake and Fast Reload, environment overrides take precedence over personal preferences, which take precedence over project defaults set through installCeraph(). Project defaults apply to collaborators who haven't made a personal choice.

Updates and privacy

Preference	Default	Purpose
Automatic updates	ask first	Choose whether Ceraph can install updates without asking each time. See Updates.
Issue reporting	ask first	Choose whether your agent can submit Ceraph bug reports without asking each time.
Installation analytics	enabled	Enable or disable minimal installation analytics with ceraph analytics on or off. See the Privacy Policy for more details.

Environment variables

Most users should leave these unset. Use them for a persistent runtime preference or when Ceraph's remediation asks for an explicit override.

Variable	Default	Purpose
CERAPH_SIGNAL_HOST	auto-detected	Troubleshooting only: override the host address when the selected device cannot reach the address Ceraph detected.
CERAPH_SIGNAL_PORT	8101	Troubleshooting only: change the host listener port when 8101 is already in use.
CERAPH_TARGET	auto	Persistent target: device, simulator, headless, emulator, no-window, or auto.
CERAPH_FAST_RELOAD	true	Set to false or 0 to disable Fast Reload for the host session.
CERAPH_WINDOW_FOCUS	true	Set to false or 0 to prevent Ceraph from bringing a simulator or emulator window to the foreground.
CERAPH_TELEMETRY	enabled	Set to 0 to disable installation analytics.
CERAPH_CAMERA_TEST_MEDIA	auto	on uses registered test media while connected; off uses the real camera; auto uses test media on simulators/emulators and the real camera on physical devices. Production always uses the real camera.
CERAPH_KEEP_AWAKE_HEARTBEAT	enabled	Set to off to disable keep-awake protection for the host session. The ordinary wake/unlock check still runs.

Updates

Ceraph automatically informs your agent when it detects a newer release. You normally don't need to check for updates yourself. To update manually:

ceraph update

By default, Ceraph asks for permission before installing an update. You can ask your agent to enable automatic updates instead at any time.

Updates preserve existing project choices and never commit changes. If an update is interrupted, follow its recovery instructions before resuming testing. When a newer version is required, testing cannot continue on the older version. Some updates change the available tools and require restarting your coding client.

Uninstalling Ceraph

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

It reverses the current project's Ceraph setup and reports a per-step status, while preserving camera fixtures and the machine-wide sign-in. Use ceraph logout separately to sign out. Only @ceraph/react-native-mcp is removed from package.json.

Ceraph remains available to your AI tools for other projects. To remove the user-level installation, run ceraph uninstall --global.

Flags

Flag	Effect
-y, --yes	Skip confirmation prompts.
--purge-data	Also delete Ceraph run data, generated local state, and this project's external build cache at ~/.ceraph/derived/<project>. Agent hooks and camera fixtures are preserved.
--dry-run	Preview the step list without writing anything.
--project-dir <path>	Operate against a specific subpackage. Required when a monorepo has more than one React Native app.
--global	Remove only user-level MCP registrations; use this flag by itself. Project setup, CLI installation, and sign-in are preserved.
--help, -h	Show uninstall help.

License

Ceraph Software License Agreement — Starter is free for internal development and testing; Pro requires an active subscription. Using Ceraph materials to recreate its features for any purpose, modification, reverse engineering, redistribution, competitive use, and bypassing subscription controls are prohibited. Documented extension points remain available for project-owned hooks, configuration, fixtures, and test artifacts.

Found a Ceraph bug? File an issue.