What It Provides

• Build & Run — Build, install, launch, and stop iOS/macOS apps on simulators and physical devices.
• Test & Coverage — Run unit/UI/build tests with filtering, streaming output, and code coverage.
• Simulator Management — Boot, shutdown, erase, configure location/appearance/status bar.
• Physical Device — Full device lifecycle via xcrun devicectl: list, pair, install, launch, terminate, screenshot, log capture.
• LLDB Debugging — Attach to simulator or device processes, set breakpoints, inspect variables, step through code.
• UI Automation — Tap, swipe, type, drag, pinch, and inspect accessibility trees on simulators (via IDB or CGEvent fallback).
• Multi-platform — tvOS, watchOS, visionOS build/run/test/discover targets.
• Swift Package Manager — Build, test, run, clean, resolve, dump, and init Swift packages.
• Project Discovery — Query the Bazel build graph, discover targets, inspect dependencies.
• Scaffolding — Generate new Bazel projects from templates (ios_app, macos_app, etc.).
• Session & Config — Workspace management, build profiles, defaults, health checks.
• Background Daemon — Per-workspace daemon for stateful operations.
• Self-update — Check for and install updates.

Requirements

• macOS with Xcode installed
• Node.js 18+
• Bazel or Bazelisk on PATH
• A Bazel workspace (set via BAZEL_IOS_WORKSPACE, config file, or set_workspace tool)

Optional (for device screenshots & logs on iOS 17+)

• pymobiledevice3 — pip3 install pymobiledevice3
• For screenshots: sudo pymobiledevice3 remote tunneld running in background
• For logs: pymobiledevice3 is tried first automatically, falls back to idevicesyslog

Installation

npm

npm install -g xcodebazelmcp

Then use the installed CLI:

xcodebazelmcp mcp

Homebrew

brew install XcodeBazelMCP/tap/xcodebazelmcp

Then use the installed CLI:

xcodebazelmcp mcp

Or run directly via npx (no install needed):

npx -y xcodebazelmcp mcp

Quick start (interactive)

npx -y xcodebazelmcp setup

Install agent skills (Cursor / Codex)

npx -y xcodebazelmcp init

MCP Configuration

{
  "mcpServers": {
    "XcodeBazelMCP": {
      "command": "npx",
      "args": ["-y", "xcodebazelmcp", "mcp"],
      "env": {
        "BAZEL_IOS_WORKSPACE": "/path/to/your/ios-workspace"
      }
    }
  }
}

If you installed the CLI globally with npm or Homebrew:

{
  "mcpServers": {
    "XcodeBazelMCP": {
      "command": "xcodebazelmcp",
      "args": ["mcp"],
      "env": {
        "BAZEL_IOS_WORKSPACE": "/path/to/your/ios-workspace"
      }
    }
  }
}

Or with workspace flag:

npx -y xcodebazelmcp mcp --workspace /path/to/your/ios-workspace

From source

git clone https://github.com/XcodeBazelMCP/XcodeBazelMCP.git
cd XcodeBazelMCP
npm install
npm run build

Working with Workspaces

XcodeBazelMCP needs to know which Bazel workspace to operate on. There are several ways to set it, in order of precedence:

1. MCP tool at runtime — bazel_ios_set_workspace (sets the workspace for later tool calls)
2. CLI flag — xcodebazelmcp mcp --workspace /path/to/workspace
3. Environment variable — BAZEL_IOS_WORKSPACE=/path/to/workspace
4. Config file — .xcodebazelmcp/config.yaml in the workspace root (supports profiles)
5. Fallback — process.cwd()

For multi-workspace setups, use profiles in config.yaml:

profiles:
  app:
    defaultTarget: '//app:app'
    defaultPlatform: simulator
    defaultBuildMode: debug
  mac:
    defaultTarget: '//mac:mac'
    defaultPlatform: macos

Then switch at runtime: xcodebazelmcp set-defaults --profile app

Environment Variables

Variable	Purpose
BAZEL_IOS_WORKSPACE	Bazel workspace root (highest-precedence workspace source).
BAZEL_PATH / MCP_BAZEL_PATH	Path to the Bazel/Bazelisk binary (defaults to bazel on PATH).
BAZEL_IOS_STARTUP_ARGS	Bazel startup args prepended to every invocation (quote-aware).
BAZEL_IOS_MCP_MAX_OUTPUT	Max captured command output in characters (default 200000).
BAZEL_IOS_SIMULATOR_CPU	Override the iOS simulator CPU (sim_arm64 / x86_64; default: host).
BAZEL_IOS_DISCOVER_SCOPE	Default discover query scope for non-monorepo workspaces (e.g. //...).
BAZEL_IOS_COMMAND_LOG	Path to the persistent NDJSON command log.
BAZEL_IOS_COMMAND_LOG_MAX_BYTES	Rotate the command log past this size (default 5 MiB).
BAZEL_IOS_COMMAND_LOG_DISABLE	Set to 1 to disable command logging.
IDB_PATH	Path to the idb binary for UI automation (else discovered on PATH).

CLI Examples

# Health check
xcodebazelmcp doctor

# Discover & query
xcodebazelmcp discover --scope //Apps/... --kind apps
xcodebazelmcp query 'deps(//app:app)'

# Build & run (simulator)
xcodebazelmcp build //app:app --debug --simulator
xcodebazelmcp run //app:app --simulator-name "iPhone 16 Pro"

# Build & run (device)
xcodebazelmcp device-run //app:app --device-name "iPhone"
xcodebazelmcp device-screenshot output.png --device-name "iPhone"
xcodebazelmcp device-log-start --device-name "iPhone"

# Test
xcodebazelmcp test //tests:UnitTests --filter "SomeTest/testCase" --stream

# macOS
xcodebazelmcp macos-build //mac:mac --debug
xcodebazelmcp macos-run //mac:mac

# Swift Package Manager
xcodebazelmcp spm-build --path ./MyPackage
xcodebazelmcp spm-test --filter "MyTests/testExample"

# Scaffold
xcodebazelmcp new ios_app MyNewApp --bundle-id com.example.MyNewApp

# Config
xcodebazelmcp defaults
xcodebazelmcp set-defaults --target //app:app --simulator-name "iPhone 16 Pro"
xcodebazelmcp workflows

Workflow Categories (125 tools)

Workflows control which tools are advertised to MCP clients. Smart defaults enable the most common workflows; use toggle-workflow to customize.

Category	Tools	Description
build	2	Build iOS targets for simulator or device
test	2	Run iOS tests with optional coverage
simulator	12	Manage simulator lifecycle, settings, media, and containers
app_lifecycle	6	Install, launch, stop, uninstall apps on simulator
capture	5	Screenshot, video recording, log capture (simulator)
agent_debug	4	NDJSON agent debug logs (Cursor DEBUG MODE)
ui_automation	9	Tap, swipe, type, drag, accessibility snapshot
deep_links	2	Open URLs and send push notifications
device	16	Physical device build, deploy, test, screenshot, logs, uninstall, list apps
lldb	10	LLDB debugger: breakpoints, variables, stepping
macos	13	macOS build, run, test, discover
tvos	4	tvOS build, run, test, discover
watchos	4	watchOS build, run, test, discover
visionos	4	visionOS build, run, test, discover
spm	7	Swift Package Manager operations
project	6	Target discovery, query, deps, rdeps
scaffold	2	Generate new Bazel projects
session	7	Workspace, defaults, profiles, health
daemon	3	Background daemon management
update	2	Self-update and version check
xcode	3	Apple-native Xcode MCP detection, DeviceHub, skills (docs)

iOS 17+ Device Notes

Apple replaced lockdownd/usbmuxd with CoreDevice (remoted) starting in iOS 17 / macOS 15. This means:

• xcrun devicectl is the only reliable CLI for device operations (list, install, launch, terminate).
• Screenshots require pymobiledevice3 with tunneld running — no devicectl screenshot subcommand exists.
• Logs use pymobiledevice3 syslog live (automatic fallback to idevicesyslog for older devices).
• Process termination uses a two-step PID lookup since devicectl doesn't expose bundleIdentifier in process listings.

See docs/device-support.md for full details.

Development

git clone https://github.com/XcodeBazelMCP/XcodeBazelMCP.git
cd XcodeBazelMCP
npm install
npm run build     # Build dist/
npm test          # Run tests (vitest)
npm run lint      # ESLint

Notes

The server launches Bazel with spawn, not a shell. Extra flags are passed as argv entries so commands are reproducible and avoid shell interpolation.