XcodeBuildMCP: Build & Test iOS Apps from Claude (2026)

TL;DR + what you need

• One package, two modes. xcodebuildmcp ships an MCP server (for agents) and a CLI (for your terminal) in the same install. Most clients run it on demand: npx -y xcodebuildmcp@latest mcp.
• Hard requirements: macOS 14.5+, Xcode 16.x+, Node 18+ (Node not needed if you install via brew install xcodebuildmcp after brew tap getsentry/xcodebuildmcp). No Windows, no Linux, no hosted mode.
• Claude Code one-liner: claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp. Cursor, Codex, Claude Desktop, and the rest are in the install section below.
• Canonical repo: github.com/getsentry/XcodeBuildMCP — yes, getsentry. The original cameroncooke/XcodeBuildMCP URL now redirects there. Same project, MIT license, still free.

From cameroncooke to getsentry: the short history

If you searched “xcodebuildmcp” and found two GitHub URLs, here’s the resolution. Cameron Cooke, a UK-based iOS developer, built XcodeBuildMCP as an open-source side project and it became the tool for agentic Apple-platform development — the thing every “Claude Code for iOS” setup guide reaches for first. In February 2026, Sentry announced it had acquired the project, with Cooke joining Sentry to keep building it full-time. The announcement cited more than 4,000 GitHub stars and an active community at the time of the deal; the repository moved to the getsentry organization, and the old URL 301-redirects.

What changed in practice: very little, deliberately. The license is still MIT, the npm package name is still xcodebuildmcp, and Sentry committed publicly to maintaining it as a supported open-source project — framing it as part of the same mobile push as its 2025 acquisition of Emerge Tools. What you gain is a funded maintainer: the 2.x line since the acquisition added a unified CLI mode, agent skills, a per-workspace daemon, an interactive docs site at xcodebuildmcp.com, and a fast release cadence. The one Sentry-shaped addition worth knowing about: the tool now uses Sentry for its own runtime error telemetry (not your code, not your prompts), with a documented opt-out — covered in the limits section.

That history is also why MCP.Directory carries two records for the same project. The canonical listing tracking the current Sentry-maintained repo is /servers/xcodebuild-mcp — used for the install panel below. The original cameroncooke-era listing lives on as /servers/xcodebuild:

XcodeBuildcameroncooke

1-Click Ready

XcodeBuild streamlines iOS app development for Apple developers with tools for building, debugging, and deploying iOS an

developer tools2.9k25

Both resolve to the same npx -y xcodebuildmcp@latest command, so nothing breaks whichever you install from. Treat the Sentry-era entry as the one that stays current.

What XcodeBuildMCP actually does

The core problem: coding agents are good at writing Swift but blind at verifying it. Raw xcodebuild output is pages of compiler, linker, and package noise; simulators are stateful; UI can’t be inspected from a shell. So the loop stalls at “I’ve made the changes — please build and tell me what happened,” and you become the agent’s eyes and hands.

XcodeBuildMCP replaces that relay with structured tools. Per the project’s own design rationale, it returns schema-backed results instead of raw terminal transcripts, remembers your workspace/scheme/simulator across calls so the agent stops repeating flags, keeps artifacts (logs, screenshots, videos) on disk instead of in chat, and turns the running UI into something an agent can reason about via semantic snapshots and accessibility-driven actions. The capability list, verified against the source tree:

• Build & run for simulators, physical devices, and macOS apps (build_run_sim, build_run_device, build_run_macos), with structured error extraction from build logs.
• Testing & coverage — test_sim, test_device, test_macos, plus get_coverage_report and per-file coverage.
• Simulator management — boot, erase, appearance, GPS location, status bar overrides, video recording.
• UI automation — tap, swipe, drag, type, key presses, screenshots, and snapshot_ui semantic hierarchies, driven by a bundled accessibility engine (AXe).
• Debugging — stateful LLDB sessions: attach, breakpoints, stack, variables, raw LLDB commands.
• Project plumbing — discover projects, list schemes, read build settings, scaffold new iOS/macOS projects, and the full Swift Package build/test/run cycle.

The maintainer’s one-line pitch for why this beats shelling out:

That token framing is the right mental model: a failing build that would dump thousands of lines into your context window comes back as a short, structured list of errors with file paths. The agent spends its context on fixing, not parsing.

Requirements

The checklist, from the official README:

• macOS 14.5 or later. The server drives Apple’s local toolchain; there is no Linux, Windows, or hosted variant.
• Xcode 16.x or later, installed with command-line tools. The server calls xcodebuild, simctl, and devicectl under the hood.
• Node.js 18.x or later for the npm/npx path. The Homebrew install bundles a runtime, so Node isn’t required there.
• For physical-device tools: code signing configured in Xcode (a signing team plus provisioning profile on the target). Simulator tools need none of this.

One README footnote that saves a confusing afternoon: the server asks xcodebuild to skip macro validation, so projects using Swift Macros build without the “target must be enabled” trust prompts that block fresh checkouts.

Install (every client)

Two ways to get the binary, both giving you the CLI and the MCP server:

# Option A — Homebrew (no Node required)
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

# Option B — npm (Node 18+)
npm install -g xcodebuildmcp@latest

# Verify either:
xcodebuildmcp --help

Or skip the global install entirely — every MCP client can launch it on demand with npx -y xcodebuildmcp@latest mcp. The install panel below pulls its config from the canonical /servers/xcodebuild-mcp entry; pick your client, copy, paste, restart.

One-line install · XcodeBuild MCP

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes that don’t fit in a panel:

• Claude Code: claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp. Add --scope project to register it in the repo’s .mcp.json for your whole team. Full flag reference at /clients/claude-code; our Claude Code best practices guide covers when project scope beats user scope.
• Cursor: add the mcpServers JSON block to .cursor/mcp.json in the workspace root.
• Codex CLI: add to ~/.codex/config.toml:

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

  The timeout bump matters: a clean build of a real app can exceed Codex’s default tool timeout, and the official docs recommend 600 seconds if you see timeout errors.
• Claude Desktop: the same JSON shape in ~/Library/Application Support/Claude/claude_desktop_config.json.
• Windsurf / Kiro / Trae / VS Code: same npx command in each client’s MCP config file — exact paths at xcodebuildmcp.com/docs/clients. Xcode’s own built-in agents (Xcode 26.3+) are also supported via a shell wrapper that fixes up PATH before launching npx.

After installing, run xcodebuildmcp init (or npx -y xcodebuildmcp@latest init) to optionally install the project’s two agent skills — one that primes the agent on the MCP tools, one for the CLI. If you pair this server with a design-side skill, the mobile-ios-design skill is the natural companion: it teaches the agent Apple’s Human Interface Guidelines and SwiftUI patterns, so XcodeBuildMCP verifies what the skill designs.

Tools walkthrough

The current release advertises roughly 80 tools, organized into workflows. That number scares people — it shouldn’t, because only the simulator workflow is enabled by default. You opt into the rest via enabledWorkflows in .xcodebuildmcp/config.yaml (or let the experimental dynamic discovery mode pull tool groups in as needed). The groups, named as they appear in the source tree:

• simulator — list_sims, boot_sim, build_sim, build_run_sim, install_app_sim, launch_app_sim, stop_app_sim, test_sim, record_sim_video. The default workflow and where most sessions live.
• simulator-management — erase simulators, set appearance (light/dark), fake GPS location, override the status bar (the clean “9:41” screenshot trick), toggle keyboards.
• device — list_devices, build_run_device, install_app_device, launch_app_device, test_device for physical iPhones/iPads over devicectl.
• macos — build, run, and test Mac apps (build_run_macos, test_macos).
• ui-automation — tap, swipe, drag, type_text, key_press, long_press, screenshot, wait_for_ui, and snapshot_ui, which returns a semantic accessibility hierarchy the agent can target instead of guessing pixel coordinates.
• debugging — debug_attach_sim, breakpoint add/remove, debug_stack, debug_variables, and raw debug_lldb_command for everything else. A stateful LLDB session, not one-shot spelunking.
• project-discovery & scaffolding — discover_projs, list_schemes, show_build_settings, plus scaffold_ios_project / scaffold_macos_project for green-field starts.
• swift-package — build, test, run, and stop Swift packages directly, no .xcodeproj required.
• session-management — session_set_defaults pins workspace, scheme, and simulator once so every later call is short. The single highest-leverage tool in the box.
• coverage, doctor, xcode-ide — test coverage reports, an environment self-check, and a bridge that can list and call the tools exposed by Xcode’s own built-in MCP server from inside XcodeBuildMCP.

Opinionated takeaway: enable simulator + ui-automation + session-management and stop. Add debugging when you’re chasing a runtime bug, device when you ship to hardware. Everything enabled at once is context weight your agent pays for on every turn.

Recipes

Recipe 1 — The fix-build-error loop

The bread and butter. Pin defaults once, then let the agent iterate:

Set session defaults: workspace MyApp.xcworkspace, scheme MyApp,
simulator "iPhone 16 Pro". Then build the app. For every error,
fix the source and rebuild until the build is green.

The agent calls session_set_defaults, then loops build_sim → edit → rebuild. Because errors come back structured (file, line, message) instead of as a raw transcript, each iteration costs a few hundred tokens, not a few thousand. For faster loops on large projects, set incrementalBuildsEnabled: true in config.yaml — it’s off by default.

Recipe 2 — Run on a simulator and verify visually

After a UI change, don’t trust the agent’s claim that it works — make it look:

Build and run on the booted simulator. Take a screenshot of the
launch screen, then snapshot the UI, tap the "Sign in" button by
its accessibility id, type a test email, and screenshot again.
Tell me what visually changed.

That’s build_run_sim → screenshot → snapshot_ui → tap → type_text → screenshot. The semantic snapshot is what makes taps reliable — the agent targets accessibility elements, not coordinates that break on the next device size.

Recipe 3 — UI test triage

A flaky XCUITest suite is a perfect agent chore: “Run the UI tests on the simulator. For each failure, pull the failure message, check coverage on the file under test, and propose whether it’s a test bug or an app bug.” The agent runs test_sim, reads the structured failure list, and cross-references get_file_coverage. For hard-to-reproduce visual failures, record_sim_video captures the run so you can watch what the test saw.

Recipe 4 — Deploy to a real device

Configure signing in Xcode first (team + provisioning profile), then: “List connected devices, build and run MyApp on my iPhone, and stream the launch logs.” That’s list_devices → build_run_device. One sharp edge from the issue tracker: launch arguments that start with dashes can be parsed by devicectl as its own flags — if you pass custom launchArgs and the app ignores them, that open issue is why. Simulator launches don’t have the problem.

Limits + gotchas

• Mac-only, local-only. The project positions itself between the agent’s inner loop and CI — it orchestrates Apple’s tools through a narrower contract, it doesn’t replace your CI pipeline or run remotely.
• Approval friction in cautious clients. With default permissions, Codex asks before every build_run_sim or session_set_defaults call — a well-trafficked r/iOSProgramming thread documents the pain. The fix is client-side: allowlist the server’s tools (or specific ones) in your client’s permission config rather than approving one call at a time.
• Discovery chatter costs tokens. If you don’t pin defaults, the agent burns turns listing simulators and schemes before every task. A .xcodebuildmcp/config.yaml with sessionDefaults kills that. Note the precedence order: tool calls during a session beat the config file, which beats environment variables.
• Known open bugs worth checking: build tools currently inject -configuration Debug even when your scheme specifies otherwise, and UI element references can go stale after a debugger-paused tap. Both are tracked on the issue tracker, which is actively triaged.
• Telemetry exists, opt-out is one line. The server reports its own runtime errors to Sentry — not your code or prompts. Set sentryDisabled: true in config.yaml if your org requires zero phone-home.

What we got wrong when we first set it up: we enabled every workflow on day one, assuming more tools meant a more capable agent. The opposite happened — tool descriptions ate context, and the agent got worse at picking the right call. The default simulator-only posture is a feature; expand it only when a task demands it.

Troubleshooting

Community signal (and the contrarian case)

XcodeBuildMCP is unusually beloved for an MCP server. A heavily-upvoted r/ClaudeAI setup guide for iOS/Swift development builds its whole workflow around it. When Apple shipped its own MCP server in the Xcode 26.3 cycle, the top question on r/iOSProgramming wasn’t “should I switch” but the reverse — the poster had used XcodeBuildMCP for months (“it’s worked perfectly”) and worried that moving to Apple’s would “cause me problems for no reason.”

The contrarian case exists and is worth hearing. Critics — including authors of competing native-Swift tools — argue the MCP approach is heavyweight: dozens of tool definitions “fighting for context” versus a handful of CLI commands, plus a Node runtime dependency and telemetry. Cooke’s public rebuttal: not all tools are exposed at once (workflows gate them), the project ships a CLI and an agent skill for exactly that lighter-weight mode, telemetry captures runtime errors only — and it’s free and MIT while several alternatives aren’t. Sentry itself published a self-aware follow-up titled “Do you really need an MCP to build your app?” — a good sign the maintainers aren’t pretending the trade-off doesn’t exist.

Our verdict: if you build for Apple platforms with any MCP client, install it — it’s the difference between an agent that writes Swift and an agent that ships working apps. Skip it only if you’re all-in on Xcode’s built-in agents and never leave the IDE, or if a no-Node, CLI-only setup is a hard requirement. For where it sits in the wider ecosystem, see our awesome MCP servers roundup.

FAQ

Sources

• Canonical repository: github.com/getsentry/XcodeBuildMCP (MIT; formerly cameroncooke/XcodeBuildMCP, which now redirects)
• Acquisition announcement: Sentry Acquires XcodeBuildMCP (Cameron Cooke & Josh Cohenzadeh, Feb 2026)
• Official docs — clients, configuration, tools, privacy: xcodebuildmcp.com/docs
• Design rationale: Why XcodeBuildMCP
• Maintainer: @camsoft2000 (Cameron Cooke)
• Community threads: r/iOSProgramming on Codex permissions & performance and Xcode’s built-in MCP vs XcodeBuildMCP; r/ClaudeAI’s iOS/Swift Claude Code setup guide
• Contrarian view from Sentry: Do you really need an MCP to build your app?
• Apple’s first-party alternative: Giving agentic coding tools access to Xcode
• Canonical MCP.Directory entries: /servers/xcodebuild-mcp (current) and /servers/xcodebuild (original listing)