react-native-mcp-kit

See, drive, and debug a running React Native app from an AI agent.

Wire it in once, and any agent that speaks the Model Context Protocol — Claude Code, Cursor, Continue, your own — can look inside your running app and act on it: read the component tree without screenshots and OCR, tail logs and network traffic, inspect navigation / Redux / React Query state, and fire real taps and keystrokes through the OS gesture pipeline.

Agent session ─ stdio/MCP ─▶ proxy ─┐
Agent session ─ stdio/MCP ─▶ proxy ─┴─▶ shared daemon ─ WebSocket ─▶ RN app (device)
                                               │
                                               └─ host tools (adb / xcrun / ios-hid) ─▶ device

Each agent session talks to a thin local proxy; the proxies share one daemon that owns the app connection and the tool catalog — so any number of editor windows see the same live app.

Nothing here ships to your users: the production babel plugin strips every trace of the library from release bundles.

What you can do with it

Ask questions about the live app. "What screen am I on?", "what did the last POST return?", "why is this list empty?" — the agent cross-references the mounted UI, navigation state, network log, and errors in one pass. No rebuild, no extra console.log, no DevTools tab.
Hand over a bug ticket. The agent drives the app into the failing state with real taps, confirms the bug, fixes the source, and replays the same steps to verify — in one editor session.
Automate flows without a test harness. "Sign in, create a document, share it, verify the recipient sees it, screenshot the result" — described in plain language, executed through the real touch pipeline, asserted on real state.
Check platforms side by side. iOS simulator, Android emulator, and a physical device can attach at once; one broadcast call runs the same step everywhere and hands back the differences.
Expose your own debug points. A component can register an ad-hoc tool from its own lifecycle (useMcpTool) — feature-flag reads, "force this loading state" actions — without shipping a debug menu.

Quick start

1. Install

yarn add react-native-mcp-kit

Peer dependencies: react >= 19, react-native >= 0.79, react-native-device-info >= 10 (device-info is optional — without it the device module just reports fewer fields).

2. Wrap the app in `McpProvider`

import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
import { McpProvider } from 'react-native-mcp-kit';

const navigationRef = createNavigationContainerRef();

export const App = () => {
  return (
    <McpProvider
      // Each prop opts a module in — omit what you don't use:
      navigationRef={navigationRef} // → navigation module
      queryClient={queryClient} // → query module
      store={store} // → redux module
      storages={[{ name: 'mmkv', adapter: mmkvAdapter }]} // → storage module
      i18n={i18nInstance} // → i18n module
    >
      <NavigationContainer ref={navigationRef}>{/* your app */}</NavigationContainer>
    </McpProvider>
  );
};

alert, console, device, errors, log_box, network, and fiber_tree register automatically — no props needed. If a dependency lives deeper in the tree (say, the QueryClient is created inside a feature provider), skip the prop and call useMcpModule there instead — see Your own tools.

3. Add the babel plugins

// babel.config.js
module.exports = (api) => {
  return {
    presets: ['module:@react-native/babel-preset'],
    plugins: [
      __DEV__
        ? 'react-native-mcp-kit/babel/test-id-plugin'
        : 'react-native-mcp-kit/babel/strip-plugin',
    ],
  };
};

test-id-plugin (dev) stamps every component with a stable data-mcp-id="Name:file:line" and records hook names — this is what lets the agent say "the second ListItem on line 76" and read isLoading instead of State[3].
strip-plugin (prod) removes everything: the provider, the hooks, the imports, the stamped attributes. You don't need if (__DEV__) guards in your code.

After editing babel config or upgrading the package, reset Metro's cache once: yarn start --reset-cache.

4. Point your agent at the server

The MCP server ships as a bin in the package. For Claude Code / Cursor, a project-local .mcp.json:

{
  "mcpServers": {
    "react-native-mcp-kit": {
      "command": "npx",
      "args": ["react-native-mcp-kit"]
    }
  }
}

Flags: --port <number> (WebSocket port the app connects to, default 8347), --no-host (in-app tools only, no device control).

Multiple agent sessions just work. Each session's MCP process is a thin proxy over one shared daemon: the first session starts it, later sessions attach to it, and every session sees the same live catalog and the same connected apps. The daemon exits on its own about a minute after it goes fully idle — no sessions AND no app connected (a running app with no open session keeps it alive). Its diagnostics land in react-native-mcp-kit-daemon.log in the OS temp dir.

Android emulators need the adb port forward once per boot: adb reverse tcp:8347 tcp:8347. iOS simulators share localhost — nothing to do.

5. Run it

Start Metro and the app; the provider connects on mount (and silently retries until the server appears). A first agent session looks like:

host__connection_status
 → { clientCount: 1, clients: [{ id: "ios-1", label: "iPhone 17 Pro", ... }] }

fiber_tree__query { steps: [{ scope: "root" }], select: [{ children: 5 }] }
 → the mounted component tree

How the agent sees it

Every tool — in-app module tools, your useMcpTool registrations, and device-level host tools — is a first-class MCP tool with a real schema in the agent's catalog. The catalog updates live: connect a second device and its tools appear; unmount a screen that registered a tool and it disappears.

Three things worth knowing:

clientId routes everything. Every tool takes an optional clientId. With one app connected you never pass it; with several, pass "ios-1", a /regex/, or an array — the latter two broadcast the call to every match and aggregate per-client results.
wait_until and assert replace sleep-and-screenshot. wait_until polls any tool until a predicate over its result holds; assert is the single-shot checkpoint version. For UI waits, fiber_tree__query has waitFor: { until: "appear" | "disappear", stable? } built in.
Responses are projection-first. Heavy JSON collapses into compact ${...} markers with path / depth / maxBytes knobs on every listing tool — the agent drills into [-1:][0].response.body instead of receiving a 50KB dump.

Device control (host tools)

Enabled by default; runs on the machine hosting the server via adb / xcrun / a bundled ios-hid binary. Works even when the app is hung, not launched, or mid-reload.

Real input — tap, long_press, swipe, drag, type_text, type_text_batch, press_key; tap_fiber finds a component via fiber_tree and taps its center in one call. iOS input is injected through the bundled ios-hid binary (no external daemons); Android goes through adb.
Screenshots — WebP, resized to keep vision-token cost low, with region cropping and an unchanged: true short-circuit for polling. Works on simulators, emulators, Android devices, and physical iOS 17+ devices (over Apple's CoreDevice tunnel — no extra tooling).
App lifecycle — launch_app / terminate_app / restart_app. Simulators use simctl; real iOS devices go through devicectl (restart is one --terminate-existing call; bare terminate isn't possible there — the tool says so).
Device listing — sims, emulators, and devices, annotated with which ones have a live MCP client attached.
Self-diagnosis — doctor checks the whole chain (daemon, connected clients, Metro reachability, whether the test-id plugin actually ran) and returns a verdict with fixes. Ask the agent to "run doctor", or run npx react-native-mcp-kit --doctor in a terminal for a human-readable report.

Real-device iOS input isn't supported yet (screenshots are) — use a simulator or Android for tap automation.

Metro tools

A separate module that talks to the Metro instance each app was bundled from — the URL is auto-detected per client at handshake, so non-default ports and LAN devices just work.

metro__symbolicate — raw Hermes/V8 stack → source paths. errors__get_errors and log_box__get_logs return stackFrames ready to feed in.
metro__reload — full JS reload on every attached app.
metro__get_events — ring buffer over Metro's event stream; catches silent HMR failures when no red box appears.
metro__status, metro__open_in_editor — ping and jump-to-line.

In-app modules

Module	What the agent gets
`fiber_tree`	Search and read the component tree — the heart of UI inspection (details)
`navigation`	Current route (+ rendering component), state, history; navigate / pop / reset / go_back
`network`	fetch + XHR log with redaction, plus request mocking: replace / modify / error / timeout
`console`	Ring buffer over console.* with stacks and monotonic ids
`errors`	Unhandled errors + promise rejections, stacks pre-parsed for symbolication
`redux`	State tree reads + dispatch
`query`	React Query cache: list, read by key, invalidate / refetch / remove / reset
`storage`	Named key-value stores (MMKV, AsyncStorage, anything with a `get`)
`device`	Platform facts: dimensions, appearance, battery, memory; open_url / vibrate / reload
`i18n`	i18next: keys, resources, search, translate, switch language
`log_box`	Inspect / dismiss / mute the LogBox overlay (handy when a warning blocks a flow)
`alert`	Native Alert from the agent — returns which button was pressed

Factories (consoleModule(options?), networkModule(options?), storageModule(...stores), …) accept options where capture behaviour is tunable — buffer sizes, captured levels, redact lists, ignored URLs. The catalog carries every tool's full schema at runtime, so the sections below stay at the "what's there" level.

fiber_tree

Search the tree with a chained query: each step narrows matches by criteria (name, testID, mcpId, text, hasProps, props, not, any — strings accept /regex/flags) within a scope (descendants, children, parent, ancestors, siblings, self, root, screen, nearest_host). Wrapper cascades (PressableView → Pressable → View → RCTView) collapse to the topmost so results don't drown in wrappers.

What you can select per match:

bounds — physical pixels, feed them straight into host__tap (or use host__tap_fiber and skip the copy-paste);
props — projected with its own path / depth / maxBytes;
hooks — hook values with source-recovered names (isLoading, not State[3]), filterable by kind / name / call-site, resolved values on request, sensitive names auto-redacted. Works through memo / forwardRef / custom HOC chains and library hooks (react-query, react-redux, reanimated);
children — a light recursive tree dump (select: [{ children: 5 }] from scope: 'root' is the canonical "show me everything" call);
refMethods — native-ref methods (focus, scrollTo, …) callable via fiber_tree__call({ method }); fiber_tree__call({ prop: 'onPress' }) invokes callback props directly when the gesture pipeline is unwanted.

Every hook entry and every stamped component carries an mcpId of the form Name:file:line — the agent can jump from a running component straight to its source line.

network — mocking

set_mock / list_mocks / remove_mock / clear_mocks let the agent control what the app receives from the backend — the missing half of the verify loop: error states a dev backend will never serve on demand. Four modes:

replace — synthesize the whole response (status / headers / body); the request never leaves the app;
modify — the real request runs, then status / headers / body are patched before the app sees them. bodyMergePatch is RFC 7396: take the real payload and flip one field ({ "feature": { "enabled": false } }), objects merge deep, null deletes a key; bodyJsonPatch is RFC 6902 for array surgery — [{ "op": "remove", "path": "/items/2" }] drops one element of the real response;
error — network failure;
timeout — the request never settles.

Matching is first-match-wins: url substring or /regex/, optional method, times (each hit consumes one), delayMs for latency simulation, and request-body constraints for endpoints that multiplex over one URL — bodyContains (substring or /regex/ over the raw body) and bodyMatch (dot-paths into the parsed JSON body: { "data.type": "courier" }). Mocks apply at the XHR layer — RN's fetch rides on XHR, so every JS-side HTTP client is covered by one interception point. They are deliberately volatile (a JS reload clears them), every mock hit is logged to the console, and affected get_requests entries carry mock: { id, mode, originalStatus? } — captured traffic never silently lies about being fake.

Your own tools

Register an ad-hoc tool from any component — it lives and dies with the component:

const EditorScreen = ({ draft }) => {
  useMcpTool(
    'get_current_draft',
    () => ({
      description: 'Snapshot of the draft currently open in the editor.',
      handler: () => ({ id: draft.id, title: draft.title, wordCount: draft.wordCount }),
    }),
    [draft]
  );
  // ...
};

Or a whole module (several tools sharing a dependency):

import { type McpModule } from 'react-native-mcp-kit';
import { z } from 'zod';

const sessionModule = (auth: AuthApi): McpModule => ({
  name: 'session',
  description: 'Auth session inspection and control',
  tools: {
    switch_account: {
      description: 'Switch to another test account by id',
      handler: async (args) => auth.switchTo(String(args.accountId)),
      inputSchema: z.looseObject({ accountId: z.string() }),
      timeout: 5000, // per-tool, default 10s
    },
  },
});

// at the root:
<McpProvider modules={[sessionModule(auth)]}>...</McpProvider>
// or from a component that owns the dependency:
useMcpModule(() => sessionModule(auth), [auth]);

Both hooks follow useMemo / useEffect semantics: the factory re-runs on dep changes, registration cleans up on unmount, and the agent's catalog follows along. For conditional registration pass null instead of a factory (or return null from it) — hooks can't be called conditionally, but a null factory registers nothing and unregisters whatever a previous render put up:

useMcpTool('get_current_draft', draft ? () => draftTool(draft) : null, [draft]);

Projecting heavy payloads

A tool that returns a cart, a state tree or a list of network calls will bury the agent's context in JSON it never asked for. Every built-in module funnels its result through one primitive first — import it for your own tools so their output speaks the same conventions:

import { applyProjection, makeProjectionSchema, projectAsValue } from 'react-native-mcp-kit/projection';
import { z } from 'zod';

const DEFAULT_DEPTH = 2;

const cartModule = (cart: CartApi): McpModule => ({
  name: 'cart',
  tools: {
    get_cart: {
      description: 'Current cart with its items and totals.',
      // `path` / `depth` / `maxBytes` / `arrayCap` … — the same args every kit tool takes.
      handler: (args) => applyProjection(cart.snapshot(), args, projectAsValue, DEFAULT_DEPTH),
      inputSchema: z.looseObject(makeProjectionSchema(DEFAULT_DEPTH)),
    },
  },
});

Containers are walked to the depth budget, wide ones are width-capped, long strings become previews, and whatever is cut leaves a sentinel marker behind (${truncated}, ${str}, ${obj}, ${cyc}) — so the agent can tell "this is all of it" from "there is more here, ask for it with path". Reach for projectValue directly when you want the { bytes, truncated, value } envelope instead.

inputSchema is a Zod schema (serialized to JSON Schema for the wire). Two habits pay off: use z.looseObject so undeclared args still reach your handler, and advertise defaults with .meta({ default }) rather than .default() — the schema guides the agent, your handler stays the source of truth. Write descriptions that name the task ("snapshot of the draft open in the editor"), not the implementation — that's what the agent's semantic tool search matches against.

Testing your app

Unit tests shouldn't load the real client (it opens a WebSocket and lazy-requires react-native). The package ships a complete no-op mock:

// jest config
moduleNameMapper: { '^react-native-mcp-kit$': 'react-native-mcp-kit/jest' }

Provider renders children, hooks no-op, factories return empty modules — fully type-compatible.

Production builds

With the strip-plugin in your production babel env, release bundles contain no trace of the library: no provider, no hooks, no stamped attributes, no imports. Dev bundles keep everything and connect automatically. There is nothing to guard, toggle, or remember at release time.

Troubleshooting

Not sure what's wrong → run the doctor. From an agent, call host__doctor; from a terminal, npx react-native-mcp-kit --doctor prints a human-readable verdict (and exits non-zero if anything's off). Either checks the daemon, connected clients, Metro, and the babel plugin in one pass and names the fix for each problem — start here before the specifics below.
Agent sees no in-app tools → check host__connection_status. No clients? The app isn't reaching the server: Android emulator missing adb reverse tcp:8347 tcp:8347, or the app was started before the server and hasn't retried yet (it retries every 3s — give it a moment).
hooks come back as null names → Metro served a cached transform without the plugin. yarn start --reset-cache once.
Could not reach or start the ... daemon → the port is held by a process that doesn't speak the daemon protocol (the verdict names it — usually a stale pre-5.1 server). Kill it, or pass --port. Daemon boot failures land in react-native-mcp-kit-daemon.log in the OS temp dir.
Daemon (pid N) runs ... vX, this session runs vY → two installs are alive (typically a daemon from an older checkout). Close the old sessions or kill the pid; the next session respawns a fresh daemon.
Client protocol vN does not match server vM → the app bundle and the server come from different package versions. Update the lagging side; the wire format is versioned deliberately so a skew fails loudly instead of degrading quietly.
Catalog feels stale after an app reload → re-check host__connection_status; tools follow client connections live, but your MCP client may need a moment to refresh.

API reference

<McpProvider /> owns the client singleton — you rarely need McpClient directly. For advanced embedding it exposes McpClient.initialize(options) / getInstance() / registerModule(s) / unregisterModule(s) / registerTool / unregisterTool / dispose / enableDebug (idempotent; initialize returns the existing instance on repeat calls). Pass debug to the provider for color-coded logs of every request and response.

interface McpModule {
  name: string;
  description?: string;
  tools: Record<string, ToolHandler>;
}

interface ToolHandler {
  description: string;
  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
  inputSchema?: ZodType; // z.looseObject({...}) — serialized to JSON Schema for the wire
  timeout?: number; // ms, default 10s
}

License

MIT

Name		Name	Last commit message	Last commit date
.vscode		.vscode
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc.js		.prettierrc.js
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.mts		vitest.config.mts
yarn.lock		yarn.lock

Navigation Menu

Repository files navigation

react-native-mcp-kit

What you can do with it

Quick start

1. Install

2. Wrap the app in `McpProvider`

3. Add the babel plugins

4. Point your agent at the server

5. Run it

How the agent sees it

Device control (host tools)

Metro tools

In-app modules

fiber_tree

network — mocking

Your own tools

Projecting heavy payloads

Testing your app

Production builds

Troubleshooting

API reference

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

react-native-mcp-kit

What you can do with it

Quick start

1. Install

2. Wrap the app in McpProvider

3. Add the babel plugins

4. Point your agent at the server

5. Run it

How the agent sees it

Device control (host tools)

Metro tools

In-app modules

fiber_tree

network — mocking

Your own tools

Projecting heavy payloads

Testing your app

Production builds

Troubleshooting

API reference

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. Wrap the app in `McpProvider`