@ceraph/react-native-mcp

MCP server for React Native and Expo development. Automatic build error capture, console monitoring, reliable screen interactions, and prebuild detection.

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

⚠️ Ignore the npm i line above. Run this once instead:

npx @ceraph/react-native-mcp init

Requirements

• Node.js 18+
• macOS (for iOS Simulator/device support)
• WebDriverAgent running on localhost:8100
• mobile-mcp for screenshots, swipe, and device management
• Expo dev client or prebuilt app (Expo Go is not supported)

Quick Setup

Run this from your project root:

npx @ceraph/react-native-mcp init

This automatically:

• Configures MCP servers for all detected clients (Claude Code, Cursor, Codex, VS Code, Windsurf, Antigravity)
• Installs a Claude Code hook that injects runtime errors into your conversation automatically
• Adds .rn-errors.json to your .gitignore

Manual Setup

If you prefer to configure manually, follow the instructions for your client below.

Claude Code

Add to .mcp.json in your project root:

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

Cursor

Add to .cursor/mcp.json in your project root:

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

Codex

Add to .codex/config.toml in your project root:

[mcp_servers.mobile-mcp]
command = "npx"
args = ["-y", "@mobilenext/mobile-mcp@latest"]

[mcp_servers.react-native-mcp]
command = "npx"
args = ["-y", "@ceraph/react-native-mcp@latest"]

VS Code / Copilot

Add to .vscode/mcp.json in your project root:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json (or Settings → Advanced Settings → Cascade):

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

Antigravity

Add to ~/.gemini/antigravity/mcp_config.json (or Manage MCP Servers → View raw config):

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

Cline / Roo Code (VS Code extensions)

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

{
  "mobile-mcp": {
    "command": "npx",
    "args": ["-y", "@mobilenext/mobile-mcp@latest"]
  },
  "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

Repeat for mobile-mcp with args -y @mobilenext/mobile-mcp@latest.

Tools

Build & Runtime

| Tool | Description | |---|---| | rn_build_ios | Build the app with expo run:ios. Captures Xcode output and returns structured errors (file, line, message, type). Optionally runs prebuild --clean first. | | rn_start | Start Metro dev server. Monitors console output for runtime errors, JS exceptions, and red screens. | | rn_get_errors | Return all captured build and runtime errors without re-running anything. | | rn_get_console | Return recent Metro console output, filtered by log level. | | rn_check_prebuild | Detect if prebuild --clean is needed by diffing package.json, app.json, and Podfile.lock against the last successful build. | | rn_stop | Kill all managed React Native processes. |

Screen Interaction

| Tool | Description | |---|---| | screen_tap | Tap at coordinates with automatic pixel ratio correction. Screenshot coordinates are divided by the device pixel ratio (2x/3x) so taps land where you expect. | | screen_find_and_tap | Find an element by text, accessibility label, or type, then tap its center. Most reliable interaction method — no coordinate guessing. |

Why both MCPs?

mobile-mcp handles low-level device interaction (screenshots, swipe, app lifecycle, recording) and is actively maintained for iOS/Android compatibility.

@ceraph/react-native-mcp adds the development workflow layer on top: structured error capture, console monitoring, pixel-ratio-corrected taps, and prebuild detection. Both talk to WebDriverAgent independently — they don't depend on each other, they complement each other.

License

MIT