### Clone, Install, and Build XcodeBuildMCP

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

Steps to clone the repository, install dependencies, install git hooks, and build the project. Includes verification steps for the CLI and starting 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

```

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

### Launch App on Simulator (New Workflow)

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

Example of launching an already installed app on a simulator using the new workflow. This replaces the legacy log-capture tools.

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

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

### Install App on Device

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

Installs an application onto a physical device.

```cli
install_app_device
```

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

### Build, Install, and Launch on Physical Device

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

Builds, installs, and launches an app on a physical device. This is the preferred single-step tool when default settings are configured.

```cli
build_run_device
```

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

### Legacy Log Capture Workflow (Before)

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

Example of the old method for starting and stopping simulator log capture. This workflow has been removed.

```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>
```

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

### Install App on Simulator

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

Installs an application onto an iOS Simulator.

```cli
install_app_sim
```

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

### Build, Install, and Launch on iOS Simulator

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

Builds, installs, and launches an app on an iOS Simulator. It also boots the simulator and attempts to open Simulator.app. Runtime logs are captured automatically, and the log file path is included in the response. This is the preferred single-step tool when default settings are configured.

```cli
build_run_sim
```

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

### Launch Installed Simulator App with Launch Arguments

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

Launches an already installed application on a simulator, providing specific runtime arguments.

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

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

### Schema Version Format Examples

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

Examples of valid 'schemaVersion' formats. Only integer strings are permitted; semver-style versions are not allowed.

```text
  * "1"
  * "2"
  * "3"
```

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

### XcodeBuildMCP Project Configuration Example

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

Example of a `.xcodebuildmcp/config.yaml` file. This file replaces environment variables for deterministic, repo-scoped behavior and takes precedence over environment variables.

```yaml
schemaVersion: 1
enabledWorkflows: ["simulator", "debugging"]
sessionDefaults:
  workspacePath: ./MyApp.xcworkspace
  scheme: MyApp
  simulatorName: iPhone 17 Pro

```

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

### XcodeBuildMCP Configuration Example

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

This JSON object shows an example configuration for XcodeBuildMCP, specifying command-line arguments and environment variables for enabling workflows, setting project paths, and configuring simulator settings.

```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"
      }
    }
  }
}
```

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

### Xcodebuildmcp Logging - After Removal (Launch App)

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

Example of launching an already installed app, which returns runtime log paths, after standalone log-capture tools were removed.

```bash
xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id com.example.MyApp

```

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

### Install XcodeBuildMCP via Homebrew

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

Use this command to install XcodeBuildMCP using Homebrew. This is the recommended method and does not require Node.js.

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

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

### Xcodebuildmcp Logging - Before Removal

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

Example of how to use standalone log-capture tools before they were removed in v2.5.0.

```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>

```

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

### CLI JSON Output Example

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

This is an example of the structured JSON output for a build-and-run command executed via the CLI.

```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": [] }
  }
}
```

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

### Setup XcodeBuildMCP Project Configuration Interactively

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

Use this command to interactively create or update your `.xcodebuildmcp/config.yaml` file.

```shell
xcodebuildmcp setup

```

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

### Install CLI Skill

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

Installs the CLI skill for XcodeBuildMCP. This command auto-detects installed AI clients and installs the skill into the appropriate directory for each.

```shell
xcodebuildmcp init
```

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

### Example Schema URL

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

An example of a constructed URL for a specific schema and version. This format allows for precise retrieval of validation schemas.

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

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

### Example Text Output for Simulator List

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

This is an example of the human-readable text output when listing simulators. It includes simulator details and suggested next steps.

```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 Agent Interaction for Build and Run

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

This prompt and agent response illustrate a typical interaction for building and running an app on a simulator, including the sequence of tool calls made by the agent.

```prompt
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)
```

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

### Example CLI Command for Stateful Tool

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

This command demonstrates how a user invokes a stateful tool like video recording. The routing to the daemon is handled internally by XcodeBuildMCP.

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

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

### New Log Capture Workflow (After)

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

Example of the new method for building and running an app, which includes runtime log paths. This replaces the legacy log-capture tools.

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

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

### Getting Tool Help

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

Obtain detailed flag information for a specific tool by appending --help.

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

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

### Minimal XcodeBuildMCP Configuration File

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

A basic configuration file example. The `schemaVersion: 1` is mandatory. Use `enabledWorkflows` to specify active tool groups.

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

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

### Install XcodeBuildMCP using npm/npx

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

Install XcodeBuildMCP globally using npm or npx. This method requires Node.js version 18 or later.

```bash
npm install -g xcodebuildmcp@latest

```

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

### Start XcodeBuildMCP in Server Mode

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

Starts the XcodeBuildMCP server, which communicates using the Model Context Protocol over stdio. This mode is typically initiated by an MCP client.

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

```

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

### Install XcodeBuildMCP globally via npm

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

Install XcodeBuildMCP globally using npm for CLI usage. This method requires Node.js.

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

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

### Start MCP Server

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

Clients spawn the MCP server over stdio. This is the command used to initiate the server process.

```shell
xcodebuildmcp mcp
```

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

### Source Schema Directory Layout

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

This example shows the directory structure for source schemas within the main repository.

```text
schemas/structured-output/
```

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

### Published Schema URL Example

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

This text example shows the format of a published schema URL, derived from the 'schema' and 'schemaVersion' fields.

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

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

### JSON Configuration for XcodeBuildMCP Server

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

Example of a JSON configuration snippet for launching the XcodeBuildMCP server with the 'mcp' subcommand.

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

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

### Xcodebuildmcp Logging - After Removal (Build and Run)

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

Example of using the build-and-run tool, which returns runtime log paths, after standalone log-capture tools were removed.

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

```

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

### Invoking XcodeBuildMCP CLI Tools

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

Examples of using the XcodeBuildMCP binary as a CLI tool to list available tools and execute specific commands like 'build-and-run' or 'snapshot-ui'.

```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
```

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

### Structured Content Example

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

Provides a structured JSON output for MCP clients, including build results and diagnostics.

```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\" })"
    ]
  }
}
```

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

### Launch XcodeBuildMCP Server: v1 vs v2

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

Compare the command-line invocation for starting the XcodeBuildMCP server in v1.x and v2.x. Version 2.x requires the 'mcp' subcommand.

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

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

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

### Published Schema Directory Layout

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

This example shows the directory structure for published schemas on the website.

```text
public/schemas/structured-output/
```

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

### Example JSON Output for Successful Build Result

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

Illustrates a successful build result in JSON format. It includes summary statistics, artifact paths, and diagnostics, along with potential next steps for running the app.

```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"
  ]
}
```

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

### Example JSON Output for Simulator List

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

Demonstrates a successful JSON response when listing simulators. It includes the schema, version, success status, simulator data, and optional next steps for automation.

```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"
  ]
}
```

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

### Example Build & Run Structured Result

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

This JSON structure represents a successful build and run operation, detailing summary statistics 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"
    }
  }
}
```

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

### Enable Additional XcodeBuildMCP Workflows

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

Configure which workflows are enabled in XcodeBuildMCP. This example enables device, debugging, and UI automation workflows in addition to the default simulator workflow.

```yaml
# .xcodebuildmcp/config.yaml
enabledWorkflows: ["simulator", "device", "debugging", "ui-automation"]
```

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

### Run All Snapshot Tests

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

Command to execute all snapshot tests and save the full output to a file for review. This is useful for initial setup or comprehensive checks.

```shell
npm run test:snapshots 2>&1 | tee /tmp/snapshot-results.txt
```

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

### Install MCP Skill to Unsupported Client

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

Prints the MCP skill content to standard output, which can then be piped to a file or directly into an unsupported client's instructions area or system prompt context.

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

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

### Manage XcodeBuildMCP Daemon Sockets

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

List, restart, or start the XcodeBuildMCP daemon in foreground mode to diagnose startup or socket issues.

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

# Force restart
xcodebuildmcp daemon restart

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

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

### Create a New Feature Branch

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

Start from an up-to-date main branch and create a focused branch for your changes. Use descriptive branch names.

```shell
git checkout main
git pull origin main
git checkout -b feature/issue-123-add-simulator-filter
```

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

### Test XcodeBuildMCP Tools via CLI

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

Examples of testing individual XcodeBuildMCP tools using the CLI without an MCP client. Useful for verifying tool behavior and manifests.

```shell
node build/cli.js simulator list
node build/cli.js simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

```

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

### Run a specific Claude UI benchmark suite

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

Use this command to execute a single benchmark suite, for example, the 'weather' suite. This is useful for targeted testing of specific UI automation changes.

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

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

### Run XcodeBuildMCP self-update

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

Execute this command to check for and install the latest version of XcodeBuildMCP. It uses the package manager you originally installed with.

```shell
xcodebuildmcp upgrade
```

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

### Build and Run on Physical Device with Launch Arguments

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

Builds and runs an app on a physical device, specifying the device ID and passing runtime arguments.

```shell
xcodebuildmcp device build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "deviceId": "<DEVICE_UDID>",
  "launchArgs": ["--uitesting"]
}'
```

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

### Initialize XcodeBuildMCP Configuration

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

Run this command to create or update your configuration file interactively. It helps in setting up project-specific defaults.

```shell
xcodebuildmcp setup
```

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

### Upgrade XcodeBuildMCP CLI

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

Checks for and installs the latest version of the XcodeBuildMCP CLI. It automatically detects the installation method (Homebrew, npm) and handles the upgrade process.

```shell
xcodebuildmcp upgrade           # show current vs latest, release notes, and confirm
```

```shell
xcodebuildmcp upgrade --check   # just tell me if there's an update, don't prompt
```

```shell
xcodebuildmcp upgrade --yes     # upgrade without asking
```

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

### Boot iOS Simulator

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

Boots an iOS simulator for manual or non-build related flows. This is not required before using the 'build_run_sim' tool.

```cli
boot_sim
```

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

### Target Specific Xcode Installation

Source: https://www.xcodebuildmcp.com/docs/xcode-ide

Set environment variables `XCODEBUILDMCP_XCODE_PID` and `XCODEBUILDMCP_XCODE_SESSION_ID` to direct the XcodeBuildMCP bridge to connect to a specific Xcode installation when multiple versions are present.

```bash
export XCODEBUILDMCP_XCODE_PID=<pid>
export XCODEBUILDMCP_XCODE_SESSION_ID=<session_id>
```

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

### List iOS Simulators

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

Lists all available iOS simulators.

```cli
list_sims
```

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

### Verify XcodeBuildMCP installation with doctor (global)

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

If installed globally via npm, use this command to run the XcodeBuildMCP doctor utility, which checks your environment for compatibility and required dependencies.

```shell
xcodebuildmcp-doctor
```

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

### Homebrew MCP Configuration

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

Configuration for XcodeBuildMCP when installed via Homebrew.

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

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

### Get MCP Environment Information

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

Displays information about the MCP environment.

```cli
doctor
```

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

### Uninstall XcodeBuildMCP using Homebrew

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

Command to uninstall XcodeBuildMCP if it was installed using Homebrew.

```shell
# Homebrew
brew uninstall xcodebuildmcp
```

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

### Build and Run with Launch Arguments (Simulator)

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

Builds and runs an app on a simulator, passing specific arguments to the application process via `launchArgs`. `extraArgs` can be used for `xcodebuild` flags.

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

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

### Get App Path on macOS

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

Retrieves the file path of a built macOS application.

```cli
get_mac_app_path
```

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

### Uninstall XcodeBuildMCP using npm

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

Command to uninstall XcodeBuildMCP if it was installed globally using npm.

```shell
# npm
npm uninstall -g xcodebuildmcp
```

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

### Run the full testing suite

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

Execute the standard test suite, including unit tests, snapshot tests, and schema fixture validation. This command serves as the baseline for contributor handoff.

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

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

### Get App Path on Device

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

Retrieves the file path of a built application on a physical device.

```cli
get_device_app_path
```

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

### Build for Device

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

Builds an application for a physical device.

```cli
build_device
```

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

### Get Code Coverage Report

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

Displays per-target code coverage data from an xcresult bundle.

```cli
get_coverage_report
```

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

### XcodeBuildMCP Configuration for Homebrew

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

This is the configuration for XcodeBuildMCP when installed via Homebrew. It specifies the command and arguments to be used.

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

```

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

### Build and Run on macOS with Launch Arguments

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

Builds and runs a macOS application, passing runtime arguments to the app process.

```shell
xcodebuildmcp macos build-and-run --json '{
  "scheme": "MyApp",
  "projectPath": "./MyApp.xcodeproj",
  "launchArgs": ["--uitesting"]
}'
```

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

### Raw Output Example

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

Outputs transcript fragments to stderr for debugging subprocess behavior. Not intended for scripting.

```shell
xcodebuildmcp simulator build \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj \
  --output raw
```

```text
$ xcodebuild -project ./MyApp.xcodeproj -scheme MyApp -destination platform=iOS Simulator,name=iPhone 17 Pro build
CompileSwift normal arm64 /repo/MyApp/ContentView.swift
Ld /tmp/DerivedData/MyApp.app/MyApp normal arm64
```

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

### Get App Path on Simulator

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

Retrieves the file path of a built application within the iOS Simulator.

```cli
get_sim_app_path
```

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

### Build and Run on Simulator

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

Combines building and running an application on an iOS simulator in a single step.

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

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

### Using Session Defaults from Config

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

Demonstrates how CLI flags are automatically filled from `.xcodebuildmcp/config.yaml` when `sessionDefaults` are set.

```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
```

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

### Get Bundle ID from macOS App

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

Extracts the bundle identifier from a macOS application package (.app).

```cli
get_mac_bundle_id
```

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

### Get Frame Variables in Debugger

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

Retrieves the variables within the current stack frame of a debugging session.

```cli
debug_variables
```

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

### Get Backtrace in Debugger

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

Retrieves the call stack (backtrace) of the current execution point in a debugging session.

```cli
debug_stack
```

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

### List Xcode Schemes

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

Lists available Xcode schemes for a project.

```cli
list_schemes
```

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

### Launch App on Device

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

Launches an application on a physical device.

```cli
launch_app_device
```

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

### Configuring MCP Server Args in config.yaml

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

Illustrates how to add the 'mcp' subcommand to the 'args' array in a configuration file for direct management.

```yaml
schemaVersion: 1
enabledWorkflows:
  - simulator
  - ui-automation
  - debugging
```

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

### Get File Code Coverage

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

Shows function-level code coverage and uncovered line ranges for a specific file.

```cli
get_file_coverage
```

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

### Add XcodeBuildMCP to Codex CLI

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

Use this command to add XcodeBuildMCP as a server for the Codex CLI. This is the basic setup.

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

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

### Launch macOS App

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

Launches an application on macOS.

```cli
launch_mac_app
```

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

### Add XcodeBuildMCP to Claude Code

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

Use this command to add XcodeBuildMCP as a server for Claude Code. This is the basic setup.

```bash
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
```

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

### Enable Xcode IDE Workflow

Source: https://www.xcodebuildmcp.com/docs/xcode-ide

Add the 'xcode-ide' workflow to your XcodeBuildMCP configuration to enable the bridge. If not enabled, the bridge will not start.

```yaml
schemaVersion: 1
enabledWorkflows: ["simulator", "debugging", "xcode-ide"]
```