XcodeBuildMCP Files

Release v2.6.0

New! Runtime UI automation

UI automation now hands your agent reusable context instead of just confirming an action ran. After a tap, swipe, type, wait, or batch, the result includes a compact snapshot of the foreground UI with stable element references and a screen hash, so the agent can pick the next control directly rather than taking another screenshot or re-running a full snapshot. Candidate controls are ranked from real accessibility data, and suggested next steps point at concrete element references instead of guessed coordinates.

In a deterministic Weather-app task, this cut wall-clock time by roughly 70%, token usage by roughly 68%, and total tool calls by roughly 76%.

New tools and options:

• wait_for_ui polls the UI until a predicate is satisfied — existence, enabled state, focus, visible text, or settled layout.
• batch performs a sequence of element-reference actions in one call, so agents can run several same-screen taps without a snapshot round-trip between each step.
• drag performs element-reference drag gestures for expanding sheets and scrolling real list regions without coordinate guessing.
• snapshot_ui now returns stable element references and a screen hash. Pass sinceScreenHash (MCP) / --since-screen-hash (CLI) to skip a full snapshot when the screen has not changed.
• type_text accepts replaceExisting to replace a field's current value instead of appending to it.

See Tools Reference.

Added

• Added follow-up nextSteps to machine-readable results so agents can act on suggested next actions without scraping prose. MCP structuredContent carries MCP tool-call hints and CLI --output json carries shell command lines. Result schemas that include nextSteps move to schema version 2; version 1 schema files remain available for existing validators. See Output Formats.
• Added an opt-in XCODEBUILDMCP_HEADLESS_LAUNCH mode for automated runs that should not steal macOS focus: macOS apps launch in the background, the Simulator window is not brought to the foreground (the simulator runtime still boots), and keyboard-shortcut actions fail fast with a clear foreground-focus requirement. See Environment Variables.

Fixed

• Fixed structured output so MCP clients that validate tool results can load every structured-output tool again. Published schemas are now self-contained, resolving validation failures such as PointerToNowhere in JSON Schema 2020-12 validators that do not re-base references across embedded schemas (#419, #423 by @Subharup-31).
• Clarified debug_attach_sim PID attach arguments so the schema documents that pid must be used without bundleId or waitFor, and invalid pid + waitFor: true calls now fail validation before LLDB is invoked (#417).
• Fixed simulator-name session defaults in the CLI so a name-only default resolves to a simulator ID for tools that take an ID, resolves before simulator lifecycle operations, and does not add conflicting simulator arguments to tools that already accept a name.
• Fixed CLI JSON output so simulator-name resolution failures return the structured error envelope instead of plain stderr, and a launch failure during resolution is no longer reported as a macOS launch failure.
• Fixed type_text so characters AXe cannot type, such as accented or other international characters, fail with a clear recoverable error before the field is focused instead of a generic typing failure.
• Fixed CLI numeric array flags so comma-separated values such as --key-codes 23,18,14 are parsed as numbers instead of failing validation.

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

Option A — Homebrew (no Node.js required)

Install:

:::bash
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

MCP config:

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

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

Install:

:::bash
npm install -g xcodebuildmcp@latest

MCP config:

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

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