Release v2.5.0-beta.1

Release v2.5.0-beta.1

Breaking

Legacy standalone log-capture tools removed

The old logging workflow and its standalone log-capture tools (start_sim_log_cap, stop_sim_log_cap, start_device_log_cap, stop_device_log_cap, and launch_app_logs_sim) have been removed. This affects users, scripts, and agents that call those tool names directly.

Use the launch or build-and-run tools instead. They return runtime log paths as part of the normal result, so agents no longer need a separate start/stop log-capture sequence.

Before:

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>

After:

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

For MCP clients, use build_run_sim, launch_app_sim, or build_run_device and read the returned runtime log path.

New! Structured outputs

XcodeBuildMCP now returns structured, machine-readable results across supported MCP clients and the CLI. Agents and scripts no longer have to scrape prose to find build status, log paths, bundle IDs, process IDs, test failures, or app paths. The human-readable text remains available, but every supported result now has a consistent envelope with the same frontmatter fields:

{
  "schema": "xcodebuildmcp.output.build-run-result",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": { }
}

For agents, this reduces token usage and makes tool results easier to act on reliably. Instead of rereading a full text transcript to find the build log, runtime log, or launched process, the agent can jump straight to fields such as data.artifacts.buildLogPath, data.artifacts.runtimeLogPath, data.artifacts.osLogPath, data.artifacts.appPath, data.artifacts.bundleId, and data.artifacts.processId.

MCP clients

MCP clients that support structured tool results receive structuredContent alongside the existing text response. The text remains useful for humans and older clients; supported clients can use the structured fields directly.

Example Build & Run result shape:

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

CLI JSON output

The CLI now supports --output text|json|jsonl|raw for tool commands. text remains the default. Use --output json when a script, CI job, or agent needs one final result document:

xcodebuildmcp simulator build-and-run --output 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": [] }
  }
}

Use --output jsonl for live progress as newline-delimited JSON, one event per line:

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

Failures use the same envelope as successes, so callers can rely on didError, error, data.summary, data.diagnostics, and test-specific fields like testCases and testFailures instead of handling every command differently.

Published schemas

The structured result contracts are published as JSON Schema and can be used to validate output or generate types:

https://xcodebuildmcp.com/schemas/structured-output/<schema-name>/<version>.schema.json

For example: xcodebuildmcp.output.build-run-result v1. See Output Formats for the full reference.

Added

• Added xcodebuildmcp upgrade to check for available updates and upgrade in place, with --check for report-only use and --yes/-y for non-interactive upgrades.
• Added a platform-aware xcodebuildmcp setup wizard: choose macOS, iOS, tvOS, watchOS, or visionOS up front; get platform-appropriate workflow recommendations; skip simulator/device prompts for macOS-only projects; and reuse previous choices when re-running setup. Single-platform setups also include the platform in generated config and --format mcp-json output. See Setup (#365, based on work by @ichoosetoaccept).
• Added XCODEBUILDMCP_CWD so MCP clients that cannot choose the server's start directory can still point project config discovery and relative-path resolution at the right workspace.
• Added per-test timing output for test runs. JSON and structured results now include a testCases list, and text output can show per-test durations with the showTestTiming config option or XCODEBUILDMCP_SHOW_TEST_TIMING=1 (#339 by @codeman9).
• Added toggle_software_keyboard and toggle_connect_hardware_keyboard tools for showing/hiding the iOS Simulator software keyboard and connecting/disconnecting the Mac hardware keyboard. See Tools Reference (#346, #347 by @yjmeqt).
• Added tvOS, watchOS, and visionOS support to build_device, so physical-device builds are no longer limited to iOS. See Device Code Signing (#352 by @bitxeno).

Changed

• CLI build and test commands now show live progress while they are running instead of waiting until the command finishes. See Output Formats.
• Runtime log capture is more reliable across server restarts and cleans itself up when apps stop or the server shuts down, reducing orphaned background log streams.
• Builds and tests now use an isolated DerivedData location per workspace or project when you have not set derivedDataPath, reducing cross-project build conflicts while keeping explicit derivedDataPath settings unchanged (#340, #341 by @codeman9).
• Long-form documentation has moved to xcodebuildmcp.com/docs, with the README focused on installation, setup, and quick links to the hosted guides.

Fixed

• Fixed a shell injection vulnerability when user-provided values were passed to Apple developer tools and log-capture queries (#289 by @sebastiondev).
• Fixed a path traversal vulnerability in structured-output schema loading so schema requests cannot read outside the bundled schema files.
• Fixed configured paths that begin with ~ or ~/ so project, workspace, DerivedData, AXe, and template paths resolve under the user's home directory instead of creating literal ~ folders. Absolute configured paths are now normalized before use (#283, supersedes #301 by @trmquang93).
• Fixed device build next-step guidance so agents no longer suggest unsupported --device-id or deviceId arguments (#287, #300 by @trmquang93, #350 by @MukundaKatta).
• Fixed Xcode IDE manual disconnect immediately reconnecting after the user explicitly disconnected it (#343, #344 by @shaun0927).
• Fixed simulator defaults refresh so stale simulator IDs are reconciled when both a simulator name and ID are configured, without rewriting shared project config files unnecessarily (#357).
• Fixed session profile JSON output so callers can rely on persisted: true after persisting a profile switch.
• Fixed some long-running commands hanging after the underlying Apple tool finished, especially when helper processes kept output streams open.
• Fixed build and test failures after command startup returnin...

Release v2.3.2

Release v2.3.2

Fixed

• Improved reliability of internal telemetry during shutdown (#302).

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.3.2

Release v2.3.1

Release v2.3.1

Fixed

• Fixed unnecessary tool confirmation prompts in MCP clients (such as Codex) that treat missing approval annotations as high-risk defaults (#297).

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.3.1

Release v2.3.0

Release v2.3.0

Added

• Added environment variable support for session defaults (e.g. XCODEBUILDMCP_WORKSPACE_PATH, XCODEBUILDMCP_SCHEME, XCODEBUILDMCP_PLATFORM) so MCP clients can supply startup defaults in their config without a project config file (#268 by @detailobsessed). See docs/CONFIGURATION.md.
• Added --format mcp-json flag to xcodebuildmcp setup that exports an env-based MCP client config block instead of writing config.yaml (#268 by @detailobsessed).

Changed

• Clarified configuration layering: session_set_defaults overrides config.yaml, which overrides environment variables. See docs/CONFIGURATION.md (#268 by @detailobsessed).
• Improved xcodebuildmcp setup reliability when optional targets (like physical devices) are unavailable.

Fixed

• Fixed .xcodebuildmcp/config.yaml being modified on startup when simulator metadata was refreshed (#230).
• Fixed orphaned MCP server processes that could remain running after the client disconnects (#273).
• Fixed list-schemes CLI command missing --project-path and --workspace-path flags (#271).
• Fixed Xcode IDE workflow tools not working when invoked from the CLI.
• Fixed Swift Package tools not properly waiting for process exit when stopping.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.3.0

Release v2.2.1

Release v2.2.1

• Fix AXe bundling issue.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.2.1

Release v2.2.0

Release v2.2.0

Added

• Added get_coverage_report and get_file_coverage tools for inspecting code coverage from test results — view per-target summaries or drill into function-level coverage and uncovered line ranges for specific files (#240 by @irangareddy). See docs/TOOLS.md.

• Added a unified build-and-run command for physical devices, matching the existing simulator workflow so agents can build and launch device apps in a single step.

• Added an interactive setup wizard via xcodebuildmcp setup that walks you through creating or updating .xcodebuildmcp/config.yaml — select workflows, pick a simulator, set your scheme and project, and configure debug options without editing YAML by hand. Non-interactive mode remains available for CI and scripting. See docs/CONFIGURATION.md.

  xcodebuildmcp setup

• Added AGENTS.md generation to the init command, providing prescriptive agent workflow instructions for your project.

• Added support for custom workflows in .xcodebuildmcp/config.yaml. Define your own workflow names and map them to an explicit list of tools, then reference them from enabledWorkflows like any built-in workflow. This lets you limit the tools your agent sees to exactly the ones you need. See docs/CONFIGURATION.md.

  enabledWorkflows: ["my-workflow"]
  customWorkflows:
    my-workflow:
      - build_run_sim
      - record_sim_video
      - screenshot

• Added AdaL CLI setup instructions (#242 by @Abdulrahmansoliman).

Changed

• CLI now auto-fills tool arguments from session defaults. If your config file sets a scheme, project path, or simulator, every CLI command picks those up automatically — no need to repeat --scheme, --project-path, and similar flags on every invocation. See docs/CLI.md.

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

  # Before: every command needed explicit flags
  xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
  
  # Now: flags are filled from session defaults
  xcodebuildmcp simulator build

  This also works with session defaults profiles, which is especially useful for monorepos. Define a profile per sub-project and the CLI uses the active profile's values. Override the profile for a single command with --profile. See docs/SESSION_DEFAULTS.md.

  # .xcodebuildmcp/config.yaml
  schemaVersion: 1
  sessionDefaultsProfiles:
    calculator:
      workspacePath: ./iOS_Calculator/CalculatorApp.xcworkspace
      scheme: CalculatorApp
      simulatorName: iPhone 17 Pro
    ios-test:
      projectPath: ./iOS/MCPTest.xcodeproj
      scheme: MCPTest
      simulatorName: iPhone 17 Pro
    spm:
      projectPath: ./spm
      scheme: spm
  activeSessionDefaultsProfile: calculator

  # Build using the active profile (calculator)
  xcodebuildmcp simulator build-and-run
  
  # Build a different sub-project without switching the active profile
  xcodebuildmcp simulator build-and-run --profile ios-test

• Default simulator updated from iPhone 16 to iPhone 17.

• Tool annotations now more accurately classify operations, reducing unnecessary confirmation prompts in MCP clients that respect annotations (#253 by @saschagordner).

• Improved agent workflow guidance with more prescriptive instructions for common tasks.

• Bundled AXe updated to 1.5.2.

Fixed

• Fixed Swift Package tools (swift_package_build, swift_package_test, swift_package_clean) hiding compiler diagnostics when stderr was empty (#255 by @doovers).
• Fixed stderr warnings (e.g. "multiple matching destinations") hiding actual test failures by prioritizing xcresult output when available (#254 by @czottmann).

Various other internal improvements to stability, performance, and code quality.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.2.0

Release v2.1.0

Release v2.1.0

Added

• Added xcodebuildmcp init CLI command to install agent skills, replacing the standalone install-skill.sh script. Supports auto-detection of AI clients (Claude Code, Cursor, Codex), --print for unsupported clients, and --uninstall for removal. See docs/SKILLS.md.
• Added namespaced session defaults profiles, letting you save and switch between different project/scheme/simulator configurations without reconfiguring each time. See docs/SESSION_DEFAULTS.md.
• Added support for persisting custom environment variables in session defaults (#235 by @kamal). See docs/SESSION_DEFAULTS.md.
• Added Kiro client setup instructions (#222 by @manojmahapatra).

Changed

• Faster MCP startup when the Xcode IDE workflow is enabled — tools are available sooner after connecting (#210). See docs/XCODE_IDE_MCPBRIDGE.md.
• Agents now use the combined build-and-run tool for simulator run intents, avoiding a redundant separate build step.
• Improved next-step suggestions so agents receive more accurate follow-up actions after each tool call.
• Updated UI automation tap guidance to prefer label and ID targets, reducing agent errors.

Fixed

• Fixed false positive error and warning detection when build output contained echoed source code (#218 by @nebooz).
• Fixed outdated tool names and parameters in the CLI skill file (#217 by @pocketpixels).
• Fixed Sentry telemetry scope to capture only internal runtime failures, removing unnecessary data collection (#204).
• Fixed a shell injection vulnerability in the release workflow (#229).
• Improved privacy redaction in the doctor command to better protect project names and paths in default output.

Removed

• Removed scripts/install-skill.sh in favour of xcodebuildmcp init.

Various other internal improvements to stability, performance, and code quality.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.1.0

Release v2.0.7

Release v2.0.7

Changed

• XcodeBuildMCP has moved to the getsentry GitHub organization. Homebrew users should switch to the new tap: brew untap cameroncooke/xcodebuildmcp && brew tap getsentry/xcodebuildmcp. npm and npx users are unaffected.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.0.7

Release v2.0.6

Release v2.0.6

Changed

• XcodeBuildMCP has moved to the getsentry GitHub organization. Homebrew users should switch to the new tap: brew untap cameroncooke/xcodebuildmcp && brew tap getsentry/xcodebuildmcp. npm and npx users are unaffected.

Option A — Homebrew (no Node.js required)

Install:

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.0.6

Release v2.0.5

Release v2.0.5

Added

• Homebrew installation (brew tap cameroncooke/xcodebuildmcp && brew install xcodebuildmcp) — installs a self-contained binary with no Node.js dependency.

Removed

• Smithery distribution channel.

Option A — Homebrew (no Node.js required)

Install:

brew tap cameroncooke/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

Option B — npm / npx (Node.js 18+)

Install:

npm install -g xcodebuildmcp@latest

MCP config:

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

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.0.5