MobileBuildMCP

Release v2.7.0

New! Xcode 27 Device Hub simulator support

UI automation tools now work fully with Xcode 27 simulators through Device Hub, including simulator window launching and keyboard controls. XcodeBuildMCP targets the selected simulator directly and uses locale-independent menu actions, while maintaining backward compatibility with Simulator.app on earlier Xcode versions.

Breaking

Build and test structured results now use schema version 3

Build and test tools now return schemaVersion: "3" so prepared-test paths can be included in structured results. This affects MCP and CLI JSON consumers that validate xcodebuildmcp.output.build-result or xcodebuildmcp.output.test-result against version 2; consumers that only display or pass through tool results are unaffected.

If no action is taken, validators pinned to version 2 will reject new build and test results. Update them to accept the version 3 schemas, while retaining version 2 support when older XcodeBuildMCP releases remain in use.

Before:

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

After:

https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.build-result/3.schema.json
https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.test-result/3.schema.json

Unspecified build configurations now follow the scheme

Build, test, clean, and app-path commands now honor the scheme action's configuration when configuration is omitted instead of always using Debug. This fixes incorrect build settings for schemes that use another configuration, but scripts or agents that relied on the implicit Debug selection must now request it explicitly.

Before:

xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

After:

xcodebuildmcp simulator build \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj \
  --configuration Debug

For MCP calls, set configuration: "Debug" (#443, #460 by @hujunfeng).

Added

• Added xcodebuildmcp purge to inspect and clean workspace storage managed by XcodeBuildMCP. It defaults to the current workspace, supports reports and dry runs, and requires explicit opt-in before removing DerivedData.
• Added reusable extraArgs session defaults for build and test commands, so common xcodebuild flags and build settings can be configured once in project config or the active session. Per-call values override matching defaults, and extraArgs: [] clears them for one call (#463 by @jknlsn). See config.example.yaml.
• Added reusable test preparation to simulator, device, and macOS workflows. Build tools can produce a portable .xctestproducts package, and test tools can run it—or an advanced .xctestrun file—without rebuilding while still producing a fresh .xcresult (#450). See CLI examples.

Fixed

• Fixed MCP clients waiting 10–17 seconds for tools to become available, which could make short health checks report a failed connection (#461, #468 by @Pitchfork-and-Torch).
• Fixed simulator commands selecting the wrong platform when a configured simulator is unavailable, especially for projects that support both iOS and visionOS. Setup now ignores unavailable simulators and records the selected platform.
• Fixed simulator and project discovery failures caused by malformed simulator data, projects w

Release v2.6.2

Fixed

• Fixed xcodebuildmcp upgrade so update checks use the latest GitHub release as the canonical target instead of stale package-manager metadata, ensuring multi-version upgrades show release notes for the actual target version.

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.6.2

Release v2.6.1

Fixed

• Fixed tab bar item discovery so agents can switch UITabBar items (#439, #441).

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.6.1

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, performan