mcp-rn-devtools

An MCP server that gives Claude (or any MCP host) real-time access to your running React Native app — including your Redux state and AsyncStorage, with zero app changes. Console logs, errors, network, state, storage, action log, navigation, performance profiling, and more.

Why this one

• True zero-config state access. A runtime agent injected over the Chrome DevTools Protocol walks the React fiber tree to discover your Redux store — no SDK, no middleware, no exposing the store on a global. Reading AsyncStorage works the same way (native module proxy). Install the server, ask Claude about your state.

• Headless. No desktop app to keep open, no toggle to remember. Works in fully autonomous agent workflows and CI.

• Secrets redacted by default. Tokens, passwords, auth headers, and JWT-shaped strings are masked server-side before anything reaches the LLM (MCP_RN_NO_REDACT=1 to opt out).

• Built for agent loops. clear_buffers → reproduce → read. wait_for_log blocks until the app emits a matching log. get_state_diff shows exactly what changed between two moments.

Related MCP server: MCP Browser Logger

How It Works

Claude / MCP Host
       │ MCP (stdio)
       ▼
  mcp-rn-devtools (server)
    ├── CDP WebSocket ──► RN App (Hermes / Metro)   ← zero config
    │     └── runtime agent (injected): Redux discovery,
    │         AsyncStorage, action log, navigation
    └── SDK WebSocket ◄── mcp-rn-devtools-sdk        ← optional enhancer

Layer 1 — CDP + runtime agent (zero config): Connects via Chrome DevTools Protocol through Metro's debugger proxy. Captures console logs, errors, warnings, and network requests, and injects a runtime agent that discovers Redux stores / React Navigation / React Query by walking the fiber tree, reads and writes AsyncStorage through the native module proxy, and records every dispatched action. Also provides JS evaluation, memory/CPU profiling, and source map resolution. No app changes needed.

Layer 2 — SDK (optional enhancer): Install mcp-rn-devtools-sdk for what the agent can't reach: Zustand/custom stores, MMKV, per-component render profiling, navigation timing, and a second capture channel that survives CDP drops.

Installation

With Claude Code

claude mcp add rn-devtools -- npx -y mcp-rn-devtools

Or add .mcp.json to your project root (shared with your team):

{
  "mcpServers": {
    "rn-devtools": {
      "command": "npx",
      "args": ["-y", "mcp-rn-devtools"]
    }
  }
}

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rn-devtools": {
      "command": "npx",
      "args": ["-y", "mcp-rn-devtools"]
    }
  }
}

Manual

npm install -g mcp-rn-devtools
mcp-rn-devtools --version

Quick Start

1. Start your React Native app — Metro must be running, Hermes engine (default since RN 0.70).

2. Add the MCP server to your Claude config (see above).

3. Ask Claude about your app:

   • "What's in my Redux store right now?"

   • "Read the AsyncStorage key persist:root"

   • "Clear the buffers, I'll reproduce the bug — then show me what happened"

   • "Dispatch auth/logout and show me the state diff"

   • "Profile the CPU for 3 seconds and show me the hot functions"

Available Tools

Source legend: agent = zero config, injected via CDP. CDP = zero config, protocol-level. SDK = requires mcp-rn-devtools-sdk in the app. Read-only tools are annotated with readOnlyHint so MCP hosts can auto-allow them.

State & Actions

Storage

Logging & Errors

Network

Diagnostics

Navigation

Memory & Performance

Advanced

Building on top of the core

The server exports its building blocks (ConnectionManager, SDKBridgeServer, the injected agent bridge, adb helpers) so tools can extend it in the same process — Hermes admits a single debugger, so extensions must share the CDP session rather than compete for it. Unrecognized SDK-channel messages are re-emitted as sdk-message events, and sendToClient() lets extensions answer.

The first product built this way is tapfix: a live QA loop for React Native (mark issues on-device or from a cockpit web UI, and an embedded coding agent fixes them on the fly). Its MCP server is a superset of this one.

Multiple sessions and multiple apps

Hermes admits one debugger per app instance, and every Claude Code session starts its own mcp-rn-devtools process. Ownership is settled per app on a device, not per machine:

• Sessions on different apps coexist. Two emulators, two apps, two sessions: each holds its own debugger. Instances register in ~/.mcp-rn-devtools/instances/ and ask each other to yield through a per-instance control endpoint — only the one holding that app is asked.

• The debugger follows the session in use for the same app. An instance attaches on its first tool call (lazy, the default); if a sibling holds that app, it yields and gets it back on its own next tool call. An instance kicked by a sibling does not fight back.

• A session attaches to its own app. The server reads the app id from the repo it runs in (android/app/build.gradle applicationId, the iOS bundle id, or Expo's app.json; MCP_RN_APP overrides) and finds that app across Metro ports 8081–8085 — a session in the wms repo attaches to wms even while picking runs on 8081. select_target also takes an app id.

• No orphans. The server exits when its MCP client goes away (stdin closes or the parent process dies).

• health_check shows the session app, who holds the debugger, the other instances and their apps, and who serves the SDK channel. list_targets marks targets held by other instances with ⊙.

Extensions that record continuously (tapfix) opt into connectMode: 'eager'. Instances older than 0.5 (no registry) are still asked to yield over the SDK port.

Secret Redaction

Every tool that outputs app data (state, storage values, network headers/bodies, action payloads) masks secrets server-side, before the data reaches the LLM:

• Values under sensitive keys (token, password, authorization, apiKey, session, cookie, …) → [REDACTED]

• JWT-shaped strings and Bearer … tokens anywhere in text → masked

Redaction is a blocklist (defence in depth, not a guarantee) — audit what your app stores before pointing any LLM at it. Opt out with MCP_RN_NO_REDACT=1.

SDK Setup (optional)

The runtime agent covers Redux, AsyncStorage, actions, and navigation with zero config. Install the SDK only if you need Zustand/custom stores, MMKV, render profiling, or navigation timing:

npm install mcp-rn-devtools-sdk --save-dev

import { RNDevtoolsProvider } from 'mcp-rn-devtools-sdk';

export default function App() {
  return (
    <RNDevtoolsProvider>
      <YourApp />
    </RNDevtoolsProvider>
  );
}

With Zustand / custom stores

const useAuthStore = create((set) => ({ /* ... */ }));

<RNDevtoolsProvider stateManagers={{ auth: useAuthStore }}>
  <YourApp />
</RNDevtoolsProvider>

State snapshots are pull-only: they're serialized only when a tool asks, so the SDK adds zero overhead while idle.

With MMKV

import { MMKV } from 'react-native-mmkv';
const storage = new MMKV();

<RNDevtoolsProvider mmkv={storage}>
  <YourApp />
</RNDevtoolsProvider>

Per-Component Render Profiling

import { RNDevtoolsProfiler } from 'mcp-rn-devtools-sdk';

<RNDevtoolsProfiler id="UserList">
  <UserList />
</RNDevtoolsProfiler>

Provider Props

The SDK automatically strips itself from production builds via __DEV__ checks — zero overhead in release.

Configuration

Architecture Notes

• Target selection: RN 0.76+ (Fusebox) no longer advertises vm: 'Hermes' — the server picks the main runtime by reactNative.capabilities.prefersFuseboxFrontend and skips secondary runtimes like Reanimated's. Legacy targets still work via the vm field.

• Kick-and-poll: CDP's awaitPromise can't resolve React Native's polyfilled Promises, so async in-app operations (AsyncStorage) fire a callback that writes to a result slot, which the server polls.

• Clock skew: log/error entries carry a server-clock receivedAt — device clocks can drift seconds from the host, which would break "wait for new logs" cuts.

• Reconnection: exponential backoff, agent re-injected automatically after every bundle reload. A pinned target that keeps failing is unpinned after 3 attempts.

• Console replay: Runtime.enable replays the runtime's console backlog on every reconnect; entries are deduplicated by (timestamp, message) so warnings do not inflate.

• global in the evaluate scope: Hermes exposes globalThis but not global to Runtime.evaluate (Metro only passes global to module factories). Injected scripts resolve the global object themselves and evaluate_js aliases global for the duration of the call.

• Multi-Metro: a known session app is searched across ports 8081–8085 regardless of what the configured port serves. Without a session app: when nothing listens on the configured port and exactly one other port has an app, the server switches to it; a running Metro without an app is left alone (the app is about to appear there), and with several candidates it asks you to select_target.

• Target identity: ownership is keyed by reactNative.logicalDeviceId (RN 0.73+: a stable hash of app + device, shared by the app's main and Reanimated runtimes), falling back to app id + device name.

• Action log caveat: the agent wraps store.dispatch at discovery time; components that captured a direct dispatch reference before discovery bypass the log (rare — discovery runs at connect).

Compatibility

• React Native: 0.71+ (validated against 0.80 / bridgeless / Fusebox)

• Engine: Hermes (default since RN 0.70)

• Platforms: iOS, Android

• Node.js: 20+

• MCP Hosts: Claude Code, Claude Desktop, or any MCP-compatible client

Development

mise install          # node 22 + pnpm 9 from .mise.toml (pnpm 10+ breaks the build)
pnpm install
pnpm build            # shared → server → sdk
pnpm test             # vitest, includes fake Metro/Hermes integration tests
pnpm typecheck && pnpm lint

Release: bump version in the three packages/*/package.json, push, and publish a GitHub Release — publish.yml runs CI and pnpm -r publish.

License

MIT