This guide covers breaking changes and required actions when upgrading from v1.x to v2.0.0.

There are two breaking changes. Most users only need to do step 1.

1. Append mcp to your server launch command.

The xcodebuildmcp binary is now a CLI. To start the MCP server you must pass the mcp subcommand. Without it the MCP client will fail to connect.

# v1.x
npx -y xcodebuildmcp@latest

# v2.0.0
npx -y xcodebuildmcp@latest mcp

If you installed via a CLI command, remove and re-add:

# Claude Code
claude mcp remove XcodeBuildMCP
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

# Codex CLI
codex mcp remove XcodeBuildMCP
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

If you manage a configuration file directly, add "mcp" as the last entry in the args array. See section 1 for file locations and examples.

2. Check your workflow configuration (if needed).

v2.0.0 defaults to loading only the simulator workflow instead of all workflows. If you already set enabledWorkflows or XCODEBUILDMCP_ENABLED_WORKFLOWS, nothing changes for you.

If you relied on the previous default and need additional workflows, add them to .xcodebuildmcp/config.yaml:

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

See section 2 for the rationale and full list of available workflows.

The xcodebuildmcp binary is now a CLI first. To start the MCP server, you must pass the mcp subcommand at the end of the launch command. Without it, the binary enters CLI mode and the MCP client will fail to connect.

Wherever your v1.x setup invoked xcodebuildmcp (or npx -y xcodebuildmcp@latest), append mcp so the final token of the command is mcp.

If you originally installed using a CLI command (e.g. claude mcp add, codex mcp add), remove the existing entry and re-add with the updated command.

Claude Code:

claude mcp remove XcodeBuildMCP
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

Codex CLI:

codex mcp remove XcodeBuildMCP
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

If you manage MCP servers through a configuration file, open it and add "mcp" as the last entry in the args array.

Common file locations:

JSON example:

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

TOML example (Codex CLI):

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]

For the full set of client-specific examples, see the README.

In v1.x, all workflows loaded by default, exposing 70+ tools. Every tool definition and its schema is sent to the LLM on each turn, consuming context window space throughout the session. While most LLM providers cache these tokens to reduce re-inference cost, they still occupy context that could otherwise be used for your code and conversation.

v2.0.0 defaults to loading only the simulator workflow (21 tools). Simulator development is the most common use case, so this covers the majority of users while keeping the token footprint small.

Other workflows -- ui-automation, debugging, device, macos, and more -- are now opt-in. This gives you direct control over the trade-off between tool breadth and token cost. Enable only what you need, when you need it.

• Already set enabledWorkflows or XCODEBUILDMCP_ENABLED_WORKFLOWS? Nothing changes.
• Relied on the default (all workflows)? You will now only see simulator tools until you opt in to additional workflows.

Create or update .xcodebuildmcp/config.yaml in your workspace root:

schemaVersion: 1
enabledWorkflows:
  - simulator
  - device
  - macos
  - ui-automation
  - debugging
  - swift-package

Set XCODEBUILDMCP_ENABLED_WORKFLOWS in your MCP client configuration:

"XcodeBuildMCP": {
  "command": "npx",
  "args": ["-y", "xcodebuildmcp@latest", "mcp"],
  "env": {
    "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,macos,ui-automation,debugging,swift-package"
  }
}

For full details on configuration options see CONFIGURATION.md. For session defaults (project, scheme, simulator, etc.) see SESSION_DEFAULTS.md.

The xcodebuildmcp command can now be used directly in the terminal without an MCP client:

# Install globally
npm install -g xcodebuildmcp@latest

# List available tools
xcodebuildmcp tools

# Build and run on simulator
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

# Take a screenshot
xcodebuildmcp simulator screenshot

# Tap a button
xcodebuildmcp ui-automation tap --label "Submit"

See CLI.md for full documentation.

The MCP server is the recommended way to use XcodeBuildMCP with coding agents and will yield the best results. The CLI is provided as an alternative and for scripting/CI use cases.

Why MCP is preferred:

• Automatic tool discovery -- tools are registered with the agent at session start, so the agent always knows what is available and how to call it.
• Session defaults -- the MCP server maintains stateful defaults (project path, scheme, simulator, etc.) across tool calls, so the agent does not have to recall and re-supply project details on every invocation. This significantly reduces errors.
• Stateful operations -- log capture, debugging sessions, and other long-running operations are fully managed by the server.

The CLI avoids the per-turn context cost of MCP tool definitions since the agent invokes commands directly with no tool schemas to transmit. However, this comes with trade-offs: session defaults are not available in CLI mode, so the agent must pass all parameters explicitly on every call. Agents also tend to consume significant tokens repeatedly calling --help to re-discover commands and arguments. The CLI skill helps reduce this discovery overhead, but in practice MCP tools are almost always used more reliably by agents.

v2.0.0 introduces optional skill files that prime your coding agent with usage instructions:

• CLI Skill -- strongly recommended when using the CLI with a coding agent.
• MCP Skill -- optional when using the MCP server; gives the agent better context on available tools.

Install via the interactive installer:

curl -fsSL https://raw.githubusercontent.com/getsentry/XcodeBuildMCP/v2.0.0/scripts/install-skill.sh -o install-skill.sh && bash install-skill.sh

See SKILLS.md for more details.

v2.0.0 adds support for a YAML config file at .xcodebuildmcp/config.yaml. This replaces the need for environment variables and provides deterministic, repo-scoped behavior. Environment variables still work but the config file takes precedence.

See CONFIGURATION.md for the full reference.