XcodeBuildMCP: an MCP server and CLI for iOS and macOS agent work

The gap XcodeBuildMCP fills between an agent and xcodebuild

An agent that can edit Swift files still cannot tell you whether the edit compiles. The missing piece is not intelligence, it is a stable interface to the local toolchain: build a scheme, boot a simulator, run tests, read the log. XcodeBuildMCP packages that interface as a Model Context Protocol server, so a client such as Cursor, Claude Code or Codex can call build and test operations as tools instead of guessing at command lines.

The audience is narrow and specific. You need a Mac, Xcode 16.x or later, and macOS 14.5 or later. The README also lists Node.js 18.x or later, but notes that Node is not required for the Homebrew installation. If your team writes iOS or macOS apps and already runs an agent in the editor, this is aimed at you. If you ship cross-platform code and only occasionally touch an Xcode project, the setup cost is hard to justify.

One design detail worth noting: the README states that XcodeBuildMCP asks xcodebuild to skip macro validation, to avoid errors when building projects that use Swift Macros. That is a deliberate default that changes what the underlying tool checks. It is convenient, and it also means the tool is not a transparent pass-through to xcodebuild.

One package, two modes: MCP server and CLI

The project ships as a single package with two entry points, and the README is explicit that either install method gives you both. The `mcp` subcommand starts the MCP server for clients. Every other command exposes a tool directly in the terminal.

The CLI keeps state through a per-workspace daemon that auto-starts when needed, which is what makes log capture and debugging possible across separate invocations. That is a real architectural commitment: the CLI is not a set of stateless wrappers, and a daemon per workspace is something you will eventually have to reason about when a command misbehaves.

On the agent side, the project also ships two optional skills. The MCP Skill primes an agent with instructions on how to use the server's tools, and the README calls it optional when you use the MCP server. The CLI Skill primes an agent on how to navigate the CLI, and the README recommends it when you use the CLI. The asymmetry is sensible: a CLI has more surface to learn than a tool list.

Tools are grouped by target. The README shows `simulator` commands for building and testing, and states separately that device tools require code signing to be configured in Xcode, with a dedicated device-signing page. Simulator work needs no signing; physical devices do.

Installing XcodeBuildMCP and running a first simulator build

Two install paths exist. Homebrew does not require Node, which matters on a machine where you would rather not add a runtime just to build an app.

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

Alternatively, install from npm. The README pins the requirement at Node.js 18 or later.

npm install -g xcodebuildmcp@latest

Either way, verify the binary responds before you touch a client config. The README gives this exact check, and you should see usage output rather than a command-not-found error.

xcodebuildmcp --help

For a first real use, build a scheme for the simulator. The README's example uses a project path and a scheme name; substitute your own.

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

If you want test products without running the tests yet, the README shows a build-for-testing variant that writes an `.xctestproducts` bundle, and a matching test command that consumes it later. That two-step flow is useful when you want the expensive compile to happen once.

xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17" --build-for-testing --test-products-path ./MyApp.xctestproducts
xcodebuildmcp simulator test --test-products-path ./MyApp.xctestproducts --simulator-name "iPhone 17"

To connect an MCP client, the README points to a clients page with drop-in config snippets for Cursor, Claude Code and Codex, and notes that most clients can run the server on demand with `npx -y xcodebuildmcp@latest mcp` instead of a global install. The README does not print those snippets inline, so read the clients page before editing a config file by hand.

The macOS and Xcode 16 constraint is the whole story

This tool cannot be your only build path. The README lists macOS 14.5 or later and Xcode 16.x or later as requirements, which rules out Linux containers and older Xcode installations entirely. A CI runner on Linux will never run it. A team still on Xcode 15 is excluded.

Device work is gated a second time. The README states that device tools require code signing to be configured in Xcode and links a device-signing page. Simulator builds sidestep signing, so the path of least resistance is simulator-only, which is also the path that tells you least about how the app behaves on real hardware.

The upgrade story is documented; the downgrade story is not. The README shows a check and an in-place upgrade.

xcodebuildmcp upgrade --check
xcodebuildmcp upgrade --yes

There is no rollback command in the README. If a new release changes how a tool behaves, your recovery path is reinstalling a specific npm version, and the README does not walk through that. Treat the upgrade flag as a one-way door until you have verified otherwise.

Telemetry is another default worth reading before adoption. The README states that XcodeBuildMCP uses Sentry for internal runtime error telemetry only, and points to a privacy page for details and opt-out instructions. The opt-out mechanism is not described in the README itself.

Where XcodeBuildMCP sits next to Apple's own MCP server

The obvious comparison is Apple's Xcode MCP server, which ships with Xcode itself. The difference is scope and dependency. Apple's server is tied to the Xcode installation and its supported client integrations. XcodeBuildMCP is an independent package with its own CLI, its own daemon, and its own install path through Homebrew or npm, and it works with clients that Apple's integration may not cover.

That independence cuts both ways. You get a terminal-first tool that is useful even without an agent, plus agent skills that Apple does not ship. You also take on a third-party dependency between your agent and your build, including a per-workspace daemon and a telemetry default that Apple's server does not have in the same form.

A second alternative is simply scripting xcodebuild yourself. A shell script calling `xcodebuild` and `xcrun simctl` has no daemon, no telemetry and no version to track. What it lacks is the MCP surface: an agent cannot discover or call your script the way it calls a registered tool, and you would be writing and maintaining the argument handling that XcodeBuildMCP already provides. If your agent workflow is one build command, the script wins. If it is a conversation that moves between build, test and log inspection, the tool interface is the point.

Maintenance, licensing and what you are actually taking on

The repository is not archived, and the last push was on 2026-09-10, which is recent enough to call the project current. The most recent release listed is v2.7.0 from 2026-07-23, with v2.6.2 and v2.6.1 before it in June. The package.json version matches v2.7.0, so the published npm package and the tagged release line up.

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. Note that the repository also carries THIRD_PARTY_LICENSES and THIRD_PARTY_PACKAGE_LICENSES.md files, so the dependency tree has its own notices that travel with the package. Read those if you vendor the code; this is not legal advice, and the notices exist precisely so you can check them yourself.

Upgrade cost is low but not zero. The upgrade commands are built in, and the project follows semantic versioning in its release numbers, so a minor bump is unlikely to break a command you depend on. The real cost is environmental: every contributor and CI machine needs macOS 14.5, Xcode 16 and, for the npm path, Node 18 or later. That is a heavier floor than most developer tools impose, and it is the constraint most likely to decide adoption for you.

Editorial conclusion

Adopt XcodeBuildMCP if your agents already edit Swift or Objective-C and you want build, simulator and test steps driven from the same session, and you are willing to stay on macOS 14.5 with Xcode 16. Skip it if you need Linux CI, non-Xcode toolchains, or a documented rollback path; the README documents upgrade but not downgrade. Before wiring it into a client, run xcodebuildmcp --help, confirm the version against the v2.7.0 release, and read the privacy page, because runtime error telemetry is sent to Sentry by default.

Frequently asked questions

Official sources

1. getsentry/XcodeBuildMCP on GitHub
2. License: MIT
3. Project website
4. README
5. Releases