Skip to content

setup.md

Latest commit

 

History

History
253 lines (186 loc) · 8.05 KB

setup.md

File metadata and controls

253 lines (186 loc) · 8.05 KB
Raw

Setup Guide

Full setup instructions for every supported client, plus platform (Android / iOS) requirements. For a one-line Claude Code install, see the README quick start.

No installation required — every client below uses npx to fetch the latest version on demand. Pick your agent:

After adding the server, fully restart the client (quit and relaunch, not just reload) so it picks up the new configuration.

Legacy package names

The npm package was previously published as react-native-ai-devtools and before that as react-native-ai-debugger. Both legacy names continue to receive identical builds via mirror-publish — existing installations and MCP configs keep working unchanged. New installs should use execbro.

Claude Code

# Project-specific (recommended) — writes .mcp.json, commit it for the team
claude mcp add execbro --scope project -- npx -y execbro@latest

# Global (all projects)
claude mcp add execbro --scope user -- npx -y execbro@latest

Prefer project scope. ExecBro does nothing without a Metro server, so a global registration starts it in every session you open, including backend and web repos where there is no simulator to talk to.

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:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
    "mcpServers": {
        "execbro": {
            "command": "npx",
            "args": ["-y", "execbro@latest"]
        }
    }
}

You can also open this file from Settings → Developer → Edit Config. Fully quit and relaunch Claude Desktop after saving.

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

Docs. Add via 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

Requires VS Code 1.102+ with Copilot (docs). Add via Cmd+Shift+P → "MCP: Add Server", or edit .vscode/mcp.json:

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

Windsurf

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

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

Zed

Docs. Open the Agent Panel settings → "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

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 (default)

AXe is a standalone CLI for iOS simulator automation. No daemon required — single binary, simple setup. Used by default; no IOS_DRIVER env var needed.

brew install cameroncooke/axe/axe

Verify: axe --version

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

Option B: IDB (alternative)

IDB (iOS Development Bridge) is a tool built by Meta for automating iOS Simulators. Requires a background daemon. Use this if you prefer IDB or hit AXe limitations.

brew install idb-companion

Verify: idb_companion --list 1

Opt in by setting IOS_DRIVER=idb in your MCP server configuration:

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

What works without a UI driver:

Capability Without AXe/IDB With AXe/IDB
Screenshots Yes (simctl) Yes
App install/launch/terminate Yes (simctl) Yes
URL opening Yes (simctl) Yes
Boot simulator Yes (simctl) Yes
Tap / swipe / gestures No Yes
Pinch to zoom (multi-touch) No No *
Text input No Yes
Accessibility tree queries No Yes
Element finding / waiting No Yes
Hardware buttons (Home, Lock) No Yes

* pinch is Android emulator only — iOS support is in progress. Neither AXe nor IDB exposes multi-touch: both drivers are strictly single-pointer, so installing one does not enable pinch on the simulator.

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: no tapping, swiping or text input, because iOS exposes no touch injection to a host below iOS 17 and ExecBro does not implement the iOS 17+ path yet.

Install the transport. 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. pymobiledevice3 mounter auto-mount is 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:

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

Pick the directory closest to your device's iOS version; a 15.5 image mounts fine on a 15.8 device. Verify with pymobiledevice3 mounter list.

The device then appears in list_devices under "iOS physical", and ios_screenshot accepts its UDID or name:

ios_screenshot with udid="fdc2d1b5937ce66..."
ios_screenshot with udid="Ihor"

Without pymobiledevice3 installed, list_devices simply shows no physical devices and a direct capture attempt tells you what to install.