XcodeBuildMCP

Preferred MCP for Apple build, test, simulator, device, and UI inspection sessions.

Prefer XcodeBuildMCP MCP tools for iOS/macOS build, test, simulator, and UI inspection. A missing tool does not itself authorize CLI or raw Xcode fallback.

Naming: MCP vs CLI

XcodeBuildMCP exposes the same implementations two ways. Names differ:

This playbook prefers MCP names. The CLI column is a capability reference, not automatic fallback permission; use it only when the active repository or user policy explicitly permits XcodeBuildMCP CLI fallback.

List everything installed locally:

xcodebuildmcp tools              # grouped by workflow
xcodebuildmcp tools --json       # machine-readable CLI verbs
xcodebuildmcp simulator build-and-run --help

Interactive config: xcodebuildmcp setup. Optional agent skill install: xcodebuildmcp init. Env diagnostics: xcodebuildmcp doctor (include doctor output on support issues).

Fast path (every MCP session)

1. Call session_show_defaults before the first build/run/test action.
2. If defaults are empty or wrong: session_set_defaults (and/or seed sessionDefaults in config). Use discover_projs only when you still need to find projects — not speculatively, and not in parallel with show-defaults.
3. For simulator run intent, prefer build_run_sim (one-shot build + install + launch) over separate build_sim → install_app_sim → launch_app_sim.
4. Prefer simulatorId (exact UDID) over name-only selection; avoid unstable “latest OS” churn when pinning a device for Maestro.
5. Report active context (project/workspace, scheme, configuration, exact simulator/device) and the exact failing tool on errors.

Capability and fallback ladder

Use the first authorized capability in this order:

Any fallback must preserve the project/workspace, scheme, configuration, exact simulator/device, serialized execution, test scope, and applicable repository commands. Every handoff reports those values, the exact tools or commands, outcomes, and residual risk. None of these tiers weakens approvals for destructive actions, deployment, publishing, credentials, or user data.

Install and configure

1. Register XcodeBuildMCP in the agent host’s MCP server list (host-specific). Server entrypoint is typically xcodebuildmcp mcp (stdio).
2. Create or edit project-local config at the consumer workspace root:

# <workspace-root>/.xcodebuildmcp/config.yaml
schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation", "debugging"]
# Optional — reduces rediscovery every session:
# sessionDefaults:
#   projectPath: "./MyApp.xcodeproj"   # or workspacePath (mutually exclusive; workspace wins if both set)
#   scheme: "MyApp"
#   simulatorId: "<UDID>"              # preferred over simulatorName when pinning
#   simulatorName: "iPhone 17 Pro"
#   configuration: "Debug"

schemaVersion: 1 is required. Layering (highest wins): session tools → config file → env vars. Details: Configuration · Session defaults.

Workflow selection (MCP context)

By default the MCP server advertises simulator tools. Session-management tools (session_show_defaults, session_set_defaults, …) are also available by default. Other workflows stay off until enabled — names from the upstream workflows catalog:

After changing config: reload or restart the MCP session.

Monorepo named profiles

For multiple apps in one repo, use sessionDefaultsProfiles + activeSessionDefaultsProfile in config, or switch at runtime with session_use_defaults_profile. Profiles are isolated (no inheritance). CLI: --profile <name> on a single invocation. See Named profiles.

Session tools (MCP)

Tool map (MCP name → CLI)

Exact advertised set depends on enabledWorkflows and XcodeBuildMCP version. Prefer the host’s live tool list. Mapping verified against 2.6.2 + official docs:

launchArgs vs extraArgs

Official contract (build-and-run and launch tools):

Applies to MCP tools such as build_run_sim, build_run_device, build_run_macos, launch_app_sim, launch_app_device, launch_mac_app (and their CLI counterparts).

CLI recipes (when explicitly permitted)

These examples use the same config file as MCP. They are available only at tier 2 of the capability ladder. Synopsis: xcodebuildmcp <workflow> <tool> [options].

# Build + run simulator (preferred one-shot)
xcodebuildmcp simulator build-and-run \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj \
  --simulator-id <UDID>

# With runtime launch args (JSON form)
xcodebuildmcp simulator build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "simulatorId": "<UDID>",
  "launchArgs": ["--uitesting"]
}'

# Tests with live progress + focused suite
xcodebuildmcp simulator test --json '{
  "workspacePath": "./MyApp.xcworkspace",
  "scheme": "MyApp",
  "simulatorId": "<UDID>",
  "progress": true,
  "extraArgs": ["-only-testing:MyAppTests"]
}'

Long-running CLI calls stream progress. For agent parsers prefer --output jsonl; humans use default text; --output json waits for a single final payload. See CLI · Output formats.

Stateful tools (log capture, video, LLDB, some SwiftPM runs) use a per-workspace daemon in CLI mode (xcodebuildmcp daemon status|logs|…). MCP keeps session state in-process.

Failure modes

More rows: Troubleshooting.

Verify after bootstrap or feature work

Goal: Prove the consumer app builds and tests on the intended target.
Constraints: Follow the capability ladder: MCP tools; explicitly permitted XcodeBuildMCP CLI; authorized repository-native tooling; otherwise blocked. No silent fallback.
Inputs: Active consumer project, scheme, simulatorId or macOS target.
Done when: session_show_defaults reported; build_run_sim or build/test executed; outcomes stated.
Verification: Prefer build_run_sim for launch; never claim pass without running the tool.

Related

• Repo MCP.md
• Maestro — pair for UI regression (same simulator ID)
• Verification matrix
• Task recipes
• Troubleshooting