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

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

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

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

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

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

Release v2.0.0

New! CLI

XcodeBuildMCP now includes a first-class CLI for direct terminal usage, scripting, and CI workflows. All the same tools available via MCP are accessible from the command line.

npm install -g xcodebuildmcp@beta
xcodebuildmcp tools # List available tools
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

Stateful operations (log capture, debugging, video recording) are backed by a per-workspace background process that starts automatically and shuts down after idle. See docs/CLI.md for full documentation.

New! Configuration File

Project-level configuration via .xcodebuildmcp/config.yaml replaces the need for environment variables. Set your project path, scheme, simulator, enabled workflows, debug settings, and more in one place. Environment variables still work but the config file takes precedence.

schemaVersion: 1
enabledWorkflows:
  - simulator
  - ui-automation
  - debugging
sessionDefaults:
  scheme: MyApp
  projectPath: ./MyApp.xcodeproj
  simulatorName: iPhone 16

See docs/CONFIGURATION.md for the full reference.

New! Xcode IDE Integration

XcodeBuildMCP can now proxy tools from Xcode 26.3's built-in MCP bridge, giving your agent access to Xcode IDE capabilities like Preview rendering, the Issue Navigator, and documentation search. Enable the xcode-ide workflow to use this. Setup instructions for both Codex Agent and Claude Code Agent in Xcode are included. See docs/XCODE_IDE_MCPBRIDGE.md for details.

Added

• LLDB Debugging: Attach a debugger to simulator apps, set breakpoints, inspect variables, view the call stack, and run LLDB commands — all through your agent. Supports both DAP and LLDB-CLI backends. See docs/TOOLS.md for the debugging tools.
• Session default persistence: Session defaults can now be saved to the config file with persist: true, so your preferred project, scheme, and simulator are remembered across sessions.
• Log subsystem filtering: Filter simulator log capture by subsystem — choose app (default), all, swiftui (for Self._printChanges() output), or a custom list of subsystems.
• Agent skills: Optional skill files that prime your agent with usage instructions for the MCP server or CLI. Install via the provided shell script or manually. See docs/SKILLS.md.
• MCP tool annotations: All tools now include MCP-standard annotations (read-only vs. destructive, idempotent, etc.) for clients that support them.
• Simulator name resolution: Session defaults now accept a simulator name and automatically resolve it to a device ID.
• Launch environment variables: Launch tools now accept an optional env object so you can pass runtime environment variables when starting apps on simulator or device.

Changed

• Simulator tools are now the default workflow. Previously all workflows loaded by default, increasing context usage.
• Bundled AXe updated to 1.3.0.
• Landscape screenshots now orient correctly.
• Simulator platform detection and default refresh behavior are more reliable, so simulator commands stay aligned with your current defaults as they change.

Fixed

• Fixed incremental builds corrupting arguments when strings contained substrings matching build flags.
• Fixed build path handling so relative project, workspace, and derived data paths resolve correctly even when commands run from different working directories.
• Fixed working-directory leakage in incremental build setup that could affect concurrent requests.
• Fixed simulator screenshot matching for similarly named devices (for example, iPhone 15 and iPhone 15 Pro).

CLI Installation

npm install -g xcodebuildmcp@2.0.0
xcodebuildmcp --help

MCP Setup

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

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

Release v2.0.0-beta.1

Installation

npm install -g xcodebuildmcp@2.0.0-beta.1

Or use with npx:

npx xcodebuildmcp@2.0.0-beta.1

📦 NPM Package: https://www.npmjs.com/package/xcodebuildmcp/v/2.0.0-beta.1

Release notes

Breaking

Workflow selection

• By default when the enabledWorkflows configuration option or XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable is not set or empty, XcodeBuildMCP will default to loading only the simulator workflow. This is a change in behaviour; previously it would load all workflows and therefore tools by default.

This change reduces the number of tools loaded by default and requires the user to opt in to enable additional sets of tools based on their project or workflow requirements.

The simulator workflow is the default because it is the most common use case based on opt-in analytics data.

For more information see the CONFIGURATION.md documentation.

• Tool names and descriptions have been made more concise to reduce token consumption. Tool argument names that are self-explanatory have had their descriptions removed entirely.

XcodeBuildMCP is now a first-class CLI

• XcodeBuildMCP now has a first class CLI interface. This allows you or your agent to invoke tools directly from the terminal which can help reduce the upfront context costs of MCP.

• When calling xcodebuildmcp without any arguments it will default to CLI mode, this is a breaking change, you must update your mcp client's configuration to pass the mcp argument:

From:

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

To:

"XcodeBuildMCP": {
  "command": "npx",
  "args": [
    "-y",
    "xcodebuildmcp@2.0.0-beta.1",
    "mcp" // <--- add this argument
  ]
}

To lean more about the CLI interface see the CLI.md documentation.

New!

• Add DAP-based debugger backend and simulator debugging toolset (attach, breakpoints, stack, variables, LLDB command).
• XcodeBuildMCP uses a new project config file at .xcodebuildmcp/config.yaml for runtime configuration, this is a more flexible and powerful way to configure XcodeBuildMCP than environment variables.

Added

• Add session-status MCP resource with session identifiers.
• Add UI automation guard that blocks UI tools when the debugger is paused.
• Add manage-workflows tool to allow agents to change the workflows enable/disabling tools at runtime. This requires clients to support tools changed notifications. (opt-in only)
• Add XcodeBuildMCP skill to improve MCP client tool use/discovery, this needs to be installed see README.md for more information.
• Added support for session-aware defaults that are persisted between sessions in the config file.

Changed

• Migrate to Zod v4.
• Remove dynamic tool discovery (discover_tools) and XCODEBUILDMCP_DYNAMIC_TOOLS. Use XCODEBUILDMCP_ENABLED_WORKFLOWS to limit startup tool registration.
• Add MCP tool annotations to all tools.

Fixed

• Update UI automation guard guidance to point at debug_continue when paused.
• Fix tool loading bugs in static tool registration.
• Fix xcodemake command argument corruption when project directory path appears as substring in non-path arguments.
• Fix snapshot_ui warning state being isolated per UI automation tool, causing false warnings.
• Fixed screenshot tool capturing rotated images when simulator is in landscape orientation by detecting window dimensions and applying +90° rotation to correct the framebuffer capture. (#186 by @VincentStark)
• Fixed Sentry ESM compatibility by upgrading @sentry/node from 10.5.0 to 10.37.0 and @sentry/cli from 2.43.1 to 3.1.0 (Fixes XCODEBUILD-MCP-13SX)

Release v1.15.1

Installation

npm install -g xcodebuildmcp@1.15.1

Or use with npx:

npx xcodebuildmcp@1.15.1

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

Release v1.15.0

Installation

npm install -g xcodebuildmcp@1.15.0

Or use with npx:

npx xcodebuildmcp@1.15.0

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