XcodeBazelMCP

A Model Context Protocol (MCP) server and CLI for Bazel-based Apple platform development. Ships 125 tools across 21 workflow categories covering iOS, macOS, tvOS, watchOS, visionOS, and Swift Package Manager.

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

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.

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.