XcodeBuildMCP

https://www.xcodebuildmcp.com/docs
Admin
An MCP server and CLI that gives AI agents full control over Xcode. Build, test, debug, and deploy...
Tokens:35,054
Snippets:539
Trust Score:7.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone, install, and build the project

Source: https://www.xcodebuildmcp.com/docs/contributing

Initial setup commands to clone the repository, install dependencies, and build the project. Includes commands to verify the build and start the MCP server.

```shell
git clone https://github.com/getsentry/XcodeBuildMCP.git
cd XcodeBuildMCP
npm install
npm run hooks:install
npm run build

# Verify the build via the CLI
node build/cli.js --help

# Or start the MCP server (stdio)
node build/cli.js mcp
```

--------------------------------

### Install via Homebrew

Source: https://www.xcodebuildmcp.com/docs/installation

Recommended installation method that does not require Node.js.

```shell
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp
```

--------------------------------

### Install via npm

Source: https://www.xcodebuildmcp.com/docs/installation

Global installation for CLI usage.

```shell
npm install -g xcodebuildmcp@latest
xcodebuildmcp --help
```

--------------------------------

### Full Configuration Schema

Source: https://www.xcodebuildmcp.com/docs/configuration

A comprehensive example of all available options in the configuration file.

```yaml
schemaVersion: 1

# Workflow selection, see /docs/workflows
enabledWorkflows: ["simulator", "ui-automation", "debugging"]
customWorkflows:
  my-workflow:
    - build_run_sim
    - record_sim_video
    - screenshot
experimentalWorkflowDiscovery: false

# Session defaults, see /docs/session-defaults
disableSessionDefaults: false
sessionDefaults:
  projectPath: "./MyApp.xcodeproj"
  scheme: "MyApp"
  simulatorName: "iPhone 17"

# Build settings
incrementalBuildsEnabled: false

# Text output
filePathRenderStyle: "list" # "list" or "tree"

# Test output
showTestTiming: false

# Debugging and telemetry
debug: false
sentryDisabled: false
debuggerBackend: "dap"
dapRequestTimeoutMs: 30000
dapLogEvents: false
launchJsonWaitMs: 8000

# UI automation
uiDebuggerGuardMode: "error"
axePath: "/opt/axe/bin/axe"

# Project templates used by scaffold tools
iosTemplatePath: "/path/to/ios/templates"
iosTemplateVersion: "v1.2.3"
macosTemplatePath: "/path/to/macos/templates"
macosTemplateVersion: "v1.2.3"
```

--------------------------------

### CLI JSONL Output Example

Source: https://www.xcodebuildmcp.com/docs/changelog

Example of newline-delimited JSON output for live progress tracking.

```jsonl
{"event":"build-result.invocation","operation":"BUILD","request":{"scheme":"CalculatorApp","platform":"iOS Simulator"}}
{"event":"build-result.build-stage","operation":"BUILD","stage":"COMPILING","message":"Compiling CalculatorApp"}
{"event":"build-result.build-summary","operation":"BUILD","status":"SUCCEEDED","durationMs":3421}
```

--------------------------------

### Example Schema File Path

Source: https://www.xcodebuildmcp.com/docs/schema-versioning

Example of a source schema file path and its corresponding published location.

```text
schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json
```

```text
public/schemas/structured-output/xcodebuildmcp.output.build-result/1.schema.json
```

--------------------------------

### Install and execute CLI commands

Source: https://www.xcodebuildmcp.com/docs/migration-v2

Install the latest version globally and invoke various simulator and UI automation tools directly from the terminal.

```shell
npm install -g xcodebuildmcp@latest

xcodebuildmcp tools
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp simulator screenshot
xcodebuildmcp ui-automation snapshot-ui --simulator-id <UDID>
xcodebuildmcp ui-automation tap --simulator-id <UDID> --element-ref e12
```

--------------------------------

### Build & Run Result Example

Source: https://www.xcodebuildmcp.com/docs/changelog

A populated example of the build-run-result schema containing summary and artifact paths.

```json
{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": {
    "summary": { "status": "SUCCEEDED", "durationMs": 1234, "target": "simulator" },
    "artifacts": {
      "appPath": "~/Library/Developer/XcodeBuildMCP/DerivedData/.../CalculatorApp.app",
      "bundleId": "io.sentry.calculatorapp",
      "processId": 99999,
      "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_run_sim_...log",
      "runtimeLogPath": "~/Library/Developer/XcodeBuildMCP/logs/io.sentry.calculatorapp_...log",
      "osLogPath": "~/Library/Developer/XcodeBuildMCP/logs/io.sentry.calculatorapp_oslog_...log"
    }
  }
}
```

--------------------------------

### build_run_sim

Source: https://www.xcodebuildmcp.com/docs/tools

Builds a scheme, installs the resulting app on a booted simulator, and launches it with captured logs.

```APIDOC
## build_run_sim

### Description
Builds the scheme, installs the resulting .app on a booted simulator, and launches it, with logs captured to a file.

### Parameters
- **scheme** (string) - Required - The scheme to build. Use list_schemes to discover valid values.
- **projectPath** (string) - Required - Absolute or relative path to .xcodeproj. Mutually exclusive with workspacePath.
- **workspacePath** (string) - Optional - Absolute or relative path to .xcworkspace. Mutually exclusive with projectPath.
- **simulatorName** (string) - Optional - Human name, e.g. "iPhone 17 Pro". Default: first booted simulator.
- **simulatorId** (string) - Optional - Simulator UUID. Takes precedence over simulatorName if both are set.
- **configuration** (string) - Optional - Build configuration. Default: Debug.
- **extraArgs** (string[]) - Optional - Additional xcodebuild and build-settings arguments.
- **launchArgs** (string[]) - Optional - Arguments passed to the launched app process.
```

--------------------------------

### Install an agent skill

Source: https://www.xcodebuildmcp.com/docs/setup

Automatically detects the client and installs the appropriate skill for improved agent performance.

```shell
xcodebuildmcp init
```

--------------------------------

### Launching Installed Simulator Apps

Source: https://www.xcodebuildmcp.com/docs/cli

Launches an app already installed on a simulator using its bundle ID.

```shell
xcodebuildmcp simulator launch-app --json '{
  "simulatorId": "<SIMULATOR_UDID>",
  "bundleId": "com.example.MyApp",
  "launchArgs": ["--uitesting"]
}'
```

--------------------------------

### Minimal Configuration Example

Source: https://www.xcodebuildmcp.com/docs/configuration

A basic configuration file requiring only the schema version and enabled workflows.

```yaml
schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation", "debugging"]
```

--------------------------------

### Execute first build

Source: https://www.xcodebuildmcp.com/docs/setup

Example interaction showing an agent discovering a project and executing a build on a simulator.

```text
You
Build and run my app on an iPhone 17 simulator and show me any runtime errors.

Agent
I'll start by discovering your project.
→ discover_projs()
→ list_schemes(projectPath: "./MyApp.xcodeproj")
→ session_set_defaults(projectPath: "./MyApp.xcodeproj", scheme: "MyApp", simulatorName: "iPhone 17")
→ build_run_sim()
→ (logs are captured to the path returned above)
```

--------------------------------

### build_run_sim

Source: https://www.xcodebuildmcp.com/docs/tools

Build, install, and launch on iOS Simulator.

```APIDOC
## build_run_sim

### Description
Build, install, and launch on iOS Simulator, booting it when needed. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
```

--------------------------------

### Install XcodeBuildMCP via Homebrew

Source: https://www.xcodebuildmcp.com/docs

Use Homebrew to install the XcodeBuildMCP binary on macOS.

```bash
brew install getsentry/xcodebuildmcp/xcodebuildmcp
```

--------------------------------

### Configure server startup for Xcode agents

Source: https://www.xcodebuildmcp.com/docs/troubleshooting

Wrap the command in zsh with a defined PATH to resolve issues where the agent starts with a minimal environment.

```toml
[mcp_servers.XcodeBuildMCP]
args = [
  "-lc",
  "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
]
command = "/bin/zsh"
enabled = true
tool_timeout_sec = 10000
```

--------------------------------

### Install xcodebuildmcp via npm

Source: https://www.xcodebuildmcp.com/docs/changelog

Use this command to install the package globally using npm. Requires Node.js 18 or higher.

```bash
npm install -g xcodebuildmcp@latest
```

--------------------------------

### Example file artifact output

Source: https://www.xcodebuildmcp.com/docs/output-formats

Displays how file artifacts are rendered in the default text output format.

```text
Files:
   ├ App Path: ~/Library/Developer/XcodeBuildMCP/.../MyApp.app
   └ Build Logs: ~/Library/Developer/XcodeBuildMCP/.../build.log
```

--------------------------------

### Start XcodeBuildMCP in MCP Server Mode

Source: https://www.xcodebuildmcp.com/docs

Launch the server via stdio for use with an MCP-compatible client.

```bash
# Started by your MCP client via stdio
xcodebuildmcp mcp
```

--------------------------------

### Start the MCP server

Source: https://www.xcodebuildmcp.com/docs/mcp-mode

Command used by MCP clients to spawn the server over stdio.

```shell
xcodebuildmcp mcp
```

--------------------------------

### Example text output for simulator list

Source: https://www.xcodebuildmcp.com/docs/output-formats

Shows the human-readable text output format for listing simulators.

```text
Available iOS Simulators:

• iPhone 17 Pro (Booted)
  UDID: 11111111-2222-3333-4444-555555555555
  Runtime: iOS 26.0

Next steps:
  xcodebuildmcp simulator build --scheme YOUR_SCHEME --simulator-id 11111111-2222-3333-4444-555555555555
```

--------------------------------

### Example Simulator List JSON Response

Source: https://www.xcodebuildmcp.com/docs/output-formats

A successful JSON response containing a list of available simulators.

```json
{
  "schema": "xcodebuildmcp.output.simulator-list",
  "schemaVersion": "2",
  "didError": false,
  "error": null,
  "data": {
    "simulators": [
      {
        "name": "iPhone 17 Pro",
        "simulatorId": "A1B2C3D4-E5F6-7890-ABCD-EF0123456789",
        "state": "Booted",
        "isAvailable": true,
        "runtime": "iOS 26.4"
      },
      {
        "name": "iPad Pro 13-inch (M5)",
        "simulatorId": "0F1E2D3C-4B5A-6978-8190-1122334455AA",
        "state": "Shutdown",
        "isAvailable": true,
        "runtime": "iOS 26.4"
      }
    ]
  },
  "nextSteps": [
    "Build an app for this simulator: xcodebuildmcp simulator build --simulator-id A1B2C3D4-E5F6-7890-ABCD-EF0123456789"
  ]
}
```

--------------------------------

### Compact UI Output Format

Source: https://www.xcodebuildmcp.com/docs/architecture-ui-automation

Example of the compact representation of UI elements provided to agents.

```text
targets: e102|tap|button|Close||xmark
scroll:  e99|swipe|scroll-view|||activePanel
text:    e130|text|text|Example value||
```

--------------------------------

### CLI JSON Output Configuration

Source: https://www.xcodebuildmcp.com/docs/changelog

Commands and example output for requesting JSON-formatted results from the CLI.

```bash
xcodebuildmcp simulator build-and-run --output json
```

```json
{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": {
    "request": { "scheme": "CalculatorApp", "platform": "iOS Simulator" },
    "summary": { "status": "SUCCEEDED", "durationMs": 1234, "target": "simulator" },
    "artifacts": { "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_run_sim_...log" },
    "diagnostics": { "warnings": [], "errors": [] }
  }
}
```

--------------------------------

### Invoke a stateful tool

Source: https://www.xcodebuildmcp.com/docs/architecture-daemon

Example of a command that triggers daemon routing to perform a long-running task like video recording.

```shell
xcodebuildmcp simulator record-video --simulator-id <UDID> --output-path ./session.mp4
```

--------------------------------

### Verify Installation

Source: https://www.xcodebuildmcp.com/docs/installation

Runs the doctor utility to validate the environment, dependencies, and feature availability.

```shell
npx --package xcodebuildmcp@latest xcodebuildmcp-doctor
```

```shell
xcodebuildmcp-doctor
```

--------------------------------

### Example Build Result JSON Response

Source: https://www.xcodebuildmcp.com/docs/output-formats

A successful JSON response following a build operation.

```json
{
  "schema": "xcodebuildmcp.output.build-result",
  "schemaVersion": "2",
  "didError": false,
  "error": null,
  "data": {
    "summary": {
      "status": "SUCCEEDED",
      "durationMs": 3421,
      "target": "simulator"
    },
    "artifacts": {
      "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_sim_20260424.log"
    },
    "diagnostics": {
      "warnings": [],
      "errors": []
    }
  },
  "nextSteps": [
    "Run the app on this simulator: xcodebuildmcp simulator build-run --scheme CalculatorApp --workspace-path example_projects/iOS_Calculator/CalculatorApp.xcworkspace"
  ]
}
```

--------------------------------

### Batch UI Automation Input Format

Source: https://www.xcodebuildmcp.com/docs/tools

Example input structure for the batch tool, using element references from UI snapshots.

```json
{"steps":[{"action":"tap","elementRef":"e1"},{"action":"tap","elementRef":"e2"}]}
```

--------------------------------

### Manage daemon lifecycle

Source: https://www.xcodebuildmcp.com/docs/architecture-daemon

Commands for inspecting, starting, stopping, or restarting the workspace-scoped daemon process.

```shell
xcodebuildmcp daemon status
xcodebuildmcp daemon start
xcodebuildmcp daemon stop
xcodebuildmcp daemon restart
xcodebuildmcp daemon list
xcodebuildmcp daemon logs
```

--------------------------------

### Type text into UI element

Source: https://www.xcodebuildmcp.com/docs/tools

Example input for typing text into a UI element using an element reference.

```json
{"elementRef":"e8","text":"London","replaceExisting":true}
```

--------------------------------

### Configure Working Directory via Environment Variable

Source: https://www.xcodebuildmcp.com/docs/env-vars

Example configuration for setting the XCODEBUILDMCP_CWD environment variable within an MCP server definition.

```json
{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
      "env": {
        "XCODEBUILDMCP_CWD": "~/Projects/MyApp"
      }
    }
  }
}
```

--------------------------------

### Run interactive storage cleanup

Source: https://www.xcodebuildmcp.com/docs/storage-management

Initiates the guided cleanup process to review and remove managed workspace storage.

```shell
xcodebuildmcp purge
```

--------------------------------

### Initialize Configuration

Source: https://www.xcodebuildmcp.com/docs/configuration

Run this command to interactively create or update the configuration file.

```shell
xcodebuildmcp setup
```

--------------------------------

### Building and Running Applications

Source: https://www.xcodebuildmcp.com/docs/cli

Builds and launches applications, optionally passing runtime arguments via JSON.

```shell
xcodebuildmcp simulator build-and-run \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj
```

```shell
xcodebuildmcp simulator build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "simulatorName": "iPhone 17 Pro",
  "launchArgs": ["--mock-weather-api"]
}'
```

--------------------------------

### Uninstall XcodeBuildMCP

Source: https://www.xcodebuildmcp.com/docs/installation

Commands to remove the package depending on the installation method used.

```shell
# Homebrew
brew uninstall xcodebuildmcp

# npm
npm uninstall -g xcodebuildmcp
```

--------------------------------

### Example Error JSON Response

Source: https://www.xcodebuildmcp.com/docs/output-formats

A JSON response indicating a validation failure.

```json
{
  "schema": "xcodebuildmcp.output.error",
  "schemaVersion": "1",
  "didError": true,
  "error": "Parameter validation failed: Invalid parameters...",
  "data": {
    "category": "validation",
    "code": "PARAMETER_VALIDATION_FAILED"
  }
}
```

--------------------------------

### show_build_settings

Source: https://www.xcodebuildmcp.com/docs/tools

Show build settings.

```APIDOC
## show_build_settings

### Description
Show build settings.

### CLI Command
`show-build-settings`
```

--------------------------------

### Configure xcodebuildmcp for Homebrew

Source: https://www.xcodebuildmcp.com/docs/changelog

Add this configuration to your MCP settings when using the Homebrew installation.

```json
"XcodeBuildMCP": {
  "command": "xcodebuildmcp",
  "args": ["mcp"]
}
```

--------------------------------

### Passing CLI Arguments

Source: https://www.xcodebuildmcp.com/docs/cli

Demonstrates passing arguments via flags, JSON strings, and configuring output formats.

```shell
# As flags
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# As JSON (useful for complex nested options)
xcodebuildmcp simulator build --json '{"scheme":"MyApp","projectPath":"./MyApp.xcodeproj"}'

# Output format
xcodebuildmcp simulator list --output json

# File artifact layout in text/raw output
xcodebuildmcp simulator build --file-path-render-style tree
```

--------------------------------

### Update XcodeBuildMCP

Source: https://www.xcodebuildmcp.com/docs/installation

Uses the built-in self-update command to check for and install newer versions.

```shell
xcodebuildmcp upgrade
```

--------------------------------

### boot_sim

Source: https://www.xcodebuildmcp.com/docs/tools

Boot iOS simulator for manual/non-build flows.

```APIDOC
## boot_sim

### Description
Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
```

--------------------------------

### Configuration File Path

Source: https://www.xcodebuildmcp.com/docs/configuration

The standard location for the project-local configuration file.

```text
<workspace-root>/.xcodebuildmcp/config.yaml
```

--------------------------------

### Migrate from Standalone Log-Capture

Source: https://www.xcodebuildmcp.com/docs/changelog

Replaces the removed logging workflow with integrated build-and-run or launch-app commands.

```bash
xcodebuildmcp logging start-sim-log-cap --simulator-id <UDID> --bundle-id com.example.MyApp
xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id com.example.MyApp
xcodebuildmcp logging stop-sim-log-cap --pid <PID>
```

```bash
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

# Or, for an app that is already installed on a simulator:
xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id com.example.MyApp
```

--------------------------------

### Troubleshoot daemon issues

Source: https://www.xcodebuildmcp.com/docs/cli

Commands and environment variables for debugging daemon startup, logs, and socket permissions.

```shell
# See logs in the foreground
xcodebuildmcp daemon start --foreground

# Extend startup timeout
export XCODEBUILDMCP_STARTUP_TIMEOUT_MS=10000

# Socket permission issues
chmod 700 ~/.xcodebuildmcp
chmod -R 700 ~/.xcodebuildmcp/daemons
```

--------------------------------

### Configure Conditional Next Steps

Source: https://www.xcodebuildmcp.com/docs/tool-authoring

Define follow-up actions in the manifest and activate them programmatically in the handler using condition keys.

```yaml
nextSteps:
  - label: Inspect a listed widget
    toolId: inspect_widget
    when: success
    condition: widgets_available
```

```typescript
if (result.widgets.length > 0) {
  ctx.nextStepConditionKeys = ['widgets_available'];
  ctx.nextStepParams = {
    inspect_widget: { name: result.widgets[0].name },
  };
}
```

--------------------------------

### List connected devices

Source: https://www.xcodebuildmcp.com/docs/device-signing

Verify that the device is recognized by the CLI after configuring signing and trusting the computer.

```shell
xcodebuildmcp device list
```

--------------------------------

### Execute XcodeBuildMCP workflows

Source: https://www.xcodebuildmcp.com/docs/cli

General syntax for invoking specific workflows and tools via the command line.

```shell
xcodebuildmcp <workflow> <tool> [options]
```

--------------------------------

### Execute Build with Minimal Output

Source: https://www.xcodebuildmcp.com/docs/output-formats

Command to perform a build with minimal JSON output style.

```shell
xcodebuildmcp simulator build --scheme CalculatorApp --workspace-path example_projects/iOS_Calculator/CalculatorApp.xcworkspace --output json --style minimal
```

--------------------------------

### Example of MCP structured output response

Source: https://www.xcodebuildmcp.com/docs/output-formats

This JSON structure demonstrates the envelope used for tool results, including the standard content array and the structuredContent object.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Build and run succeeded for CalculatorApp."
    }
  ],
  "structuredContent": {
    "schema": "xcodebuildmcp.output.build-run-result",
    "schemaVersion": "2",
    "didError": false,
    "error": null,
    "data": {
      "summary": {
        "status": "SUCCEEDED",
        "durationMs": 3421,
        "target": "simulator"
      },
      "artifacts": {
        "appPath": "~/Library/Developer/XcodeBuildMCP/DerivedData/Build/Products/Debug-iphonesimulator/CalculatorApp.app",
        "bundleId": "io.sentry.calculatorapp",
        "processId": 91827,
        "simulatorId": "A1B2C3D4-E5F6-7890-ABCD-EF0123456789",
        "buildLogPath": "~/Library/Developer/XcodeBuildMCP/logs/build_run_sim_20260424.log",
        "runtimeLogPath": "~/Library/Developer/XcodeBuildMCP/logs/io.sentry.calculatorapp_20260424.log"
      },
      "diagnostics": {
        "warnings": [],
        "errors": []
      }
    },
    "nextSteps": [
      "Capture a screenshot of the launched app: screenshot({ simulatorId: \"A1B2C3D4-E5F6-7890-ABCD-EF0123456789\" })"
    ]
  }
}
```

--------------------------------

### Run standard test suites

Source: https://www.xcodebuildmcp.com/docs/testing

Execute the baseline test commands for unit tests, snapshots, and schema fixtures.

```shell
npm test
npm run test:snapshots
npm run test:schema-fixtures
```

--------------------------------

### Structured Test Result JSON

Source: https://www.xcodebuildmcp.com/docs/output-formats

Example of the structured JSON output returned by test tools, containing summary data, individual test cases, and diagnostic information.

```json
{
  "schema": "xcodebuildmcp.output.test-result",
  "schemaVersion": "2",
  "didError": false,
  "error": null,
  "data": {
    "summary": {
      "status": "FAILED",
      "durationMs": 22100,
      "counts": { "passed": 21, "failed": 2, "skipped": 0 },
      "target": "simulator"
    },
    "testCases": [
      { "suite": "CalculatorAppTests", "test": "testAddition", "status": "passed", "durationMs": 1 },
      { "suite": "CalculatorAppTests", "test": "testCalculatorServiceFailure", "status": "failed", "durationMs": 4 },
      { "suite": "IntentionalFailureTests", "test": "test", "status": "failed", "durationMs": 3 }
    ],
    "diagnostics": {
      "warnings": [],
      "errors": [],
      "testFailures": [
        {
          "suite": "CalculatorAppTests",
          "test": "testCalculatorServiceFailure",
          "message": "XCTAssertEqual failed: (\"0\") is not equal to (\"999\")",
          "location": "CalculatorAppTests/CalculatorAppTests.swift:52"
        }
      ]
    }
  }
}
```

--------------------------------

### Structured Content Envelope Example

Source: https://www.xcodebuildmcp.com/docs/mcp-protocol-support

The standard JSON envelope used for all tool outputs, containing schema metadata, error status, and optional follow-up automation steps.

```json
{
  "schema": "xcodebuildmcp.output.simulator-list",
  "schemaVersion": "2",
  "didError": false,
  "error": null,
  "data": {},
  "nextSteps": [
    "Build an app for this simulator: build_sim({ simulatorId: \"A1B2C3D4-E5F6-7890-ABCD-EF0123456789\" })"
  ]
}
```

--------------------------------

### Validate Documentation and Schemas

Source: https://www.xcodebuildmcp.com/docs/tool-authoring

Run these commands to verify tool metadata, documentation, and structured output schemas.

```shell
npm run docs:check
```

```shell
npm run test:schema-fixtures
npx vitest run src/core/__tests__/structured-output-schema.test.ts
```

--------------------------------

### launch_mac_app

Source: https://www.xcodebuildmcp.com/docs/tools

Launch a macOS application.

```APIDOC
## launch_mac_app

### Description
Launch a macOS application.

### CLI Command
`launch`
```

--------------------------------

### Bootstrap Defaults via Environment Variables

Source: https://www.xcodebuildmcp.com/docs/session-defaults

Supply workspace context to the MCP client using environment variables when direct configuration is unavailable.

```json
{
  "env": {
    "XCODEBUILDMCP_WORKSPACE_PATH": "/repo/MyApp.xcworkspace",
    "XCODEBUILDMCP_SCHEME": "MyApp",
    "XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 17 Pro"
  }
}
```

--------------------------------

### Print Skill Content to File

Source: https://www.xcodebuildmcp.com/docs/skills

Outputs the MCP skill content to stdout for manual integration into clients without a native skills directory.

```shell
xcodebuildmcp init --print --skill mcp > my-mcp-skill.md
```

--------------------------------

### Perform dry-run cleanup

Source: https://www.xcodebuildmcp.com/docs/storage-management

Simulate deletion to preview the plan without removing files. Use the --older-than flag to filter by age.

```shell
xcodebuildmcp purge --dry-run --scope current --classes logs,resultBundles,stateTransients
```

```shell
xcodebuildmcp purge --dry-run --scope current --classes derivedData --older-than 7d
```

--------------------------------

### swift_package_list

Source: https://www.xcodebuildmcp.com/docs/tools

List SwiftPM processes.

```APIDOC
## swift_package_list

### Description
List SwiftPM processes.

### CLI Command
`list`
```

--------------------------------

### List simulators with default text output

Source: https://www.xcodebuildmcp.com/docs/output-formats

Executes the simulator list command using the default text output format.

```shell
xcodebuildmcp simulator list
```

--------------------------------

### Run Claude UI benchmark suites

Source: https://www.xcodebuildmcp.com/docs/testing

Commands to execute specific or all benchmark suites, with options for machine-readable output and re-rendering existing results.

```shell
npm run bench:claude-ui -- --suite weather
```

```shell
npm run bench:claude-ui -- --all
```

```shell
npm run bench:claude-ui -- --suite weather --json
```

```shell
npm run bench:claude-ui -- --from-result out.nosync/claude-benchmarks/weather/<timestamp>/result.json
```

--------------------------------

### Configure XcodeBuildMCP for Claude Desktop

Source: https://www.xcodebuildmcp.com/docs/clients

Add the server definition to the Claude Desktop configuration file located in the application support directory.

```json
{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}
```

--------------------------------

### Update Server Launch Command

Source: https://www.xcodebuildmcp.com/docs/migration-v2

The v2.x CLI requires the 'mcp' subcommand to initiate the MCP server.

```shell
# v1.x
npx -y xcodebuildmcp@latest

# v2.x
npx -y xcodebuildmcp@latest mcp
```

--------------------------------

### Execute UI Automation Snapshot

Source: https://www.xcodebuildmcp.com/docs/output-formats

Command to capture a UI snapshot with verbose output enabled.

```shell
xcodebuildmcp ui-automation snapshot-ui --simulator-id <UDID> --output json --verbose
```

--------------------------------

### Configure MCP client for development

Source: https://www.xcodebuildmcp.com/docs/contributing

JSON configuration for an MCP client to point to the local development build of the server.

```json
{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "node",
      "args": ["/path/to/XcodeBuildMCP/build/cli.js", "mcp"],
      "env": {
        "XCODEBUILDMCP_DEBUG": "true"
      }
    }
  }
}
```

--------------------------------

### open_sim

Source: https://www.xcodebuildmcp.com/docs/tools

Open the simulator frontend for visibility and manual workflows.

```APIDOC
## open_sim

### Description
Open the simulator frontend for visibility and manual workflows. Not required before simulator build-and-run.

### CLI Command
`open`
```

--------------------------------

### Configure OpenCode for XcodeBuildMCP

Source: https://www.xcodebuildmcp.com/docs/clients

Add this configuration to your project-level opencode.json file to enable the MCP server.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "XcodeBuildMCP": {
      "type": "local",
      "command": ["npx", "-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}
```

--------------------------------

### Configure Session Defaults in config.yaml

Source: https://www.xcodebuildmcp.com/docs/session-defaults

Define global session defaults during server startup by adding a sessionDefaults block to the configuration file.

```yaml
schemaVersion: 1
sessionDefaults:
  projectPath: "./MyApp.xcodeproj"
  scheme: "MyApp"
  simulatorName: "iPhone 17 Pro"
  configuration: "Debug"
```

--------------------------------

### swift_package_run

Source: https://www.xcodebuildmcp.com/docs/tools

Swift package target run.

```APIDOC
## swift_package_run

### Description
Swift package target run.

### CLI Command
`run`
```

--------------------------------

### Bundle AXe locally

Source: https://www.xcodebuildmcp.com/docs/contributing

Downloads pre-built AXe artifacts into the bundled/axe directory for UI automation or simulator capture tools.

```bash
npm run bundle:axe
```

--------------------------------

### Access tool-specific help

Source: https://www.xcodebuildmcp.com/docs/cli

Retrieve detailed flag information for a specific tool.

```shell
xcodebuildmcp simulator build --help
```

--------------------------------

### swift_package_build

Source: https://www.xcodebuildmcp.com/docs/tools

Swift package target build.

```APIDOC
## swift_package_build

### Description
Swift package target build.

### CLI Command
`build`
```

--------------------------------

### snapshot_ui

Source: https://www.xcodebuildmcp.com/docs/tools

Capture a semantic rs/1 runtime UI snapshot.

```APIDOC
## snapshot_ui

### Description
Capture a semantic rs/1 runtime UI snapshot with elementRef targets.

### CLI Command
`snapshot-ui`
```

--------------------------------

### Building for iOS Simulator

Source: https://www.xcodebuildmcp.com/docs/cli

Executes a build for a specific iOS simulator using explicit flags.

```shell
xcodebuildmcp simulator build \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj \
  --simulator-name "iPhone 17 Pro"
```

--------------------------------

### Configure XcodeBuildMCP in MCP Client

Source: https://www.xcodebuildmcp.com/docs/env-vars

Define the server command and environment variables within the MCP client configuration file.

```json
{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
      "env": {
        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,debugging,ui-automation",
        "XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
        "XCODEBUILDMCP_SCHEME": "MyApp",
        "XCODEBUILDMCP_PLATFORM": "iOS Simulator",
        "XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 17 Pro"
      }
    }
  }
}
```

--------------------------------

### list_schemes

Source: https://www.xcodebuildmcp.com/docs/tools

List Xcode schemes.

```APIDOC
## list_schemes

### Description
List Xcode schemes.

### CLI Command
`list-schemes`
```

--------------------------------

### Set daemon startup timeout

Source: https://www.xcodebuildmcp.com/docs/troubleshooting

Extend the daemon startup timeout using an environment variable.

```shell
export XCODEBUILDMCP_STARTUP_TIMEOUT_MS=10000
```

--------------------------------

### Configure CLI output format

Source: https://www.xcodebuildmcp.com/docs/output-formats

Use the --output flag to specify the desired format for tool results.

```shell
xcodebuildmcp simulator list --output json
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --output jsonl
```

--------------------------------

### Server Initialization Capabilities

Source: https://www.xcodebuildmcp.com/docs/mcp-protocol-support

The capability shape advertised by the server during the MCP initialize process.

```json
{
  "tools": {
    "listChanged": true
  },
  "resources": {
    "subscribe": true,
    "listChanged": true
  },
  "logging": {}
}
```

--------------------------------

### Manage daemon processes

Source: https://www.xcodebuildmcp.com/docs/troubleshooting

Commands to list, restart, or debug the XcodeBuildMCP daemon.

```shell
# Check for stale sockets
xcodebuildmcp daemon list

# Force restart
xcodebuildmcp daemon restart

# Run in the foreground to see logs
xcodebuildmcp daemon start --foreground
```

--------------------------------

### Define a Tool Manifest

Source: https://www.xcodebuildmcp.com/docs/tool-authoring

Create a YAML file in manifests/tools/ to define tool metadata, including identifiers, module paths, and output schemas.

```yaml
id: list_widgets
module: mcp/tools/simulator/list_widgets
names:
  mcp: list_widgets
  cli: list-widgets
description: List available widgets.
availability:
  mcp: true
  cli: true
annotations:
  title: List Widgets
  readOnlyHint: true
  destructiveHint: false
  openWorldHint: false
outputSchema:
  schema: xcodebuildmcp.output.widget-list
  version: "1"
```

--------------------------------

### Configuring Session Defaults

Source: https://www.xcodebuildmcp.com/docs/cli

Defines default project settings in a YAML configuration file to simplify CLI invocations.

```yaml
# .xcodebuildmcp/config.yaml
schemaVersion: 1
sessionDefaults:
  scheme: MyApp
  projectPath: ./MyApp.xcodeproj
  simulatorName: iPhone 17 Pro
```

```shell
# Before: flags on every invocation
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# Now: flags come from session defaults
xcodebuildmcp simulator build
```

--------------------------------

### Reference Schema File Path

Source: https://www.xcodebuildmcp.com/docs/schema-versioning

Path format for referencing specific schema versions.

```text
schemas/structured-output/xcodebuildmcp.output.build-result/2.schema.json
```

--------------------------------

### Add XcodeBuildMCP via Codex CLI

Source: https://www.xcodebuildmcp.com/docs/clients

Use the Codex CLI to register the MCP server directly from the terminal.

```bash
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
```
Tokens:
Raw