Platform & IDE Setup

Requirements

• Node.js 18+
• React Native app running with Metro bundler
• Recommended: execbro-sdk in your app — wires stores and the network layer into the agent for dramatically better debugging (optional; ExecBro works without it)
• iOS UI automation: Facebook IDB or AXe CLI — required for tap, swipe, text input, accessibility on iOS Simulator
• Physical iOS screenshots: pymobiledevice3 — only needed to capture a USB-attached iPhone/iPad; interaction on physical devices is not supported

No installation required — every client below uses npx to fetch the latest version on demand. After saving the configuration, fully quit and relaunch the client so it picks up the new server.

Claude Code

claude mcp add execbro --scope project -- npx -y execbro@latest

claude mcp add execbro --scope user -- npx -y execbro@latest

Project scope writes a .mcp.jsonyou can commit, so the whole team picks ExecBro up in this repo and nowhere else. Global scope starts it in every session you open, including repos with no Metro server to connect to — convenient if you work in React Native all day, wasteful otherwise.

Or edit ~/.claude.json (user) / .mcp.json (project) manually:

{
  "mcpServers": {
    "execbro": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

Claude Desktop

Edit the config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). You can also open it from Settings → Developer → Edit Config.

{
  "mcpServers": {
    "execbro": {
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

Codex CLI (OpenAI)

codex mcp add execbro -- npx -y execbro@latest

Or edit ~/.codex/config.toml directly:

[mcp_servers.execbro]
command = "npx"
args = ["-y", "execbro@latest"]

Cursor

Via Command Palette: Cmd+Shift+P→ "View: Open MCP Settings". Or edit .cursor/mcp.json (project) / ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "execbro": {
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

VS Code Copilot (1.102+)

Via Command Palette: Cmd+Shift+P→ "MCP: Add Server". Or edit .vscode/mcp.json:

{
  "servers": {
    "execbro": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "execbro": {
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

Zed

Open the Agent Panel settings and click "Add Custom Server", or add to settings.json:

{
  "context_servers": {
    "execbro": {
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ],
      "env": {}
    }
  }
}

Gemini CLI

Edit ~/.gemini/settings.json (user) or .gemini/settings.json (project):

{
  "mcpServers": {
    "execbro": {
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ]
    }
  }
}

Android Setup

Android works out of the box — all device control tools use ADB, which ships with Android Studio. Verify it's available:

adb devices

iOS Simulator — UI Automation Setup

iOS UI automation tools (tap, swipe, text input, accessibility queries) require a UI driver. Install one of the following:

Option A: AXe CLI (experimental)

AXe is a standalone CLI for iOS simulator automation. No daemon required — single binary, simple setup.

brew install cameroncooke/axe/axe

Verify: axe --version

Add env to your MCP server configuration:

{
  "mcpServers": {
    "execbro": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "execbro@latest"
      ],
      "env": {
        "IOS_DRIVER": "axe"
      }
    }
  }
}

Note: AXe text input only supports US keyboard layout characters.

Option B: IDB (default)

IDB (iOS Development Bridge) is a tool built by Meta for automating iOS Simulators. Requires a background daemon.

brew install idb-companion

Verify: idb_companion --list 1

IDB is the default driver — no IOS_DRIVER env var needed.

What works without a UI driver

Troubleshooting:If you see errors like "IDB is not installed" or "AXe is not installed" in tap results, install the appropriate driver with the commands above and retry.

Physical iOS Device — Screenshots

ios_screenshot can capture a USB-attached iPhone or iPad. This is capture only: tap, swipe and text input reach the Simulator, not a physical device, because iOS exposes no touch injection to a host below iOS 17.

There is no Homebrew formula for it, and plain pip install is refused on current macOS (externally-managed-environment), so install it as an isolated CLI tool:

brew install pipx
pipx install pymobiledevice3

If you already use uv, uv tool install pymobiledevice3 does the same thing. Both land the binary in ~/.local/bin, which ExecBro checks directly — so it works even when your MCP client is launched from the GUI and does not inherit your shell PATH.

Then mount the DeveloperDiskImage once per device. mounter auto-mountis the documented route but fails on a stock machine — it tries to write into a root-owned Xcode directory — so mount Xcode's existing image instead, picking the version closest to your device:

X=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport/15.5
pymobiledevice3 mounter mount-developer \
  "$X/DeveloperDiskImage.dmg" "$X/DeveloperDiskImage.dmg.signature"

The device then appears in list_devicesunder "iOS physical", and ios_screenshot accepts its UDID or name. Without pymobiledevice3 installed, no physical devices are listed and nothing else changes.

Install the SDK (recommended)

ExecBro works with zero app changes, but installing the companion execbro-sdk package is the single biggest upgrade to debugging quality. It lets you wire the important parts of your app — your state stores and your network layer — directly into the agent's reach, so the AI inspects real Redux / TanStack Query state and full request/response bodies instead of guessing from the outside.

Under the hood, the MCP server connects over Chrome DevTools Protocol (CDP), which misses events that fire before it attaches and can't read request/response bodies on newer architectures. The SDK patches fetch and console at import time and buffers everything in-app from the very first line — the MCP server auto-detects it, no extra config.

npm install execbro-sdk

Initialize in your app's entry file ( index.js, App.tsx, or app/_layout.tsx for Expo Router) as the first import, and pass in the stores and references you want the agent to reach:

import { init } from 'execbro-sdk';
import { store } from './store'; // Redux store
import { queryClient } from './queryClient'; // TanStack Query
import { navigationRef } from './navigation';

if (__DEV__) {
  init({
    stores: { redux: store, queryClient },
    navigation: navigationRef,
  });
}

init() alone already unlocks full log and network capture. Wiring stores, navigation, or custom references is what hands the agent direct control — it can read and act through any object you pass in, not just your state and navigation but AsyncStorage, MMKV, or any other reference you choose to expose. See the SDK guide for every option.