XcodeBuildMCP: An MCP Server and CLI for Agent-Driven iOS and macOS Builds
A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
At a glance
- What is it?
- XcodeBuildMCP exposes xcodebuild to coding agents through the Model Context Protocol and also ships a terminal CLI. It is useful when an agent needs to compile, test or debug an Apple project, and awkward when the workflow lives on Linux or in a non-Xcode toolchain.
- Who is it for?
- Adopt XcodeBuildMCP if your agents already work inside Xcode projects on macOS 14.5 or later with Xcode 16.x, and you want build, test and debug steps driven through the MCP tools rather than pasted shell commands. Skip it if your CI runs on Linux, if you build with Bazel or Tuist, or if device work is central and code signing is not configured in Xcode.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap XcodeBuildMCP fills between an agent and xcodebuild
A coding agent that can edit Swift files still cannot answer the question that matters: does the project build? Answering it means invoking xcodebuild with the right scheme, project or workspace path, destination and derived data settings, then parsing output that is verbose and inconsistent across failure modes. Agents that improvise shell commands get this wrong often enough that the loop becomes edit, guess, retry.
XcodeBuildMCP addresses that by registering build, test and debug operations as MCP tools, so the agent calls a named tool with structured arguments instead of constructing a command line. The project describes itself as an MCP server and CLI that provides tools for agent use when working on iOS and macOS projects. The audience is narrow and identifiable: developers running agents such as Cursor, Claude Code or Codex against an Xcode project on a Mac. If your work happens outside Xcode, the tool has nothing to offer.
One package, two surfaces: the MCP server and the CLI
The installation section states that XcodeBuildMCP ships as a single package with two modes. The mcp subcommand starts the MCP server for clients; every other subcommand exposes the same tools directly in a terminal. That is a deliberate design choice, and it changes how you debug agent behaviour. When an agent's build call fails, you can run the equivalent CLI command yourself and compare.
The CLI also keeps a per-workspace daemon for stateful operations such as log capture and debugging, and the README says it auto-starts when needed. That daemon is the piece worth understanding before adoption. Stateful operations are exactly the ones that do not map cleanly onto a stateless tool call, so the project moves that state out of the MCP request cycle and into a long-lived process. The README does not document the daemon's lifecycle in detail, so how it behaves across workspace switches or crashed sessions is something to verify rather than assume.
Build, test and debug tools and how a call is shaped
The CLI section gives the concrete shape of a build call: xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj. The flags mirror xcodebuild concepts (scheme, project path, simulator name) rather than inventing an abstraction over them. That matters for anyone deciding whether to adopt it: the mental model you already have for xcodebuild transfers, and the tool arguments are legible to a reviewer who has never seen the project.
Testing splits into two steps. One command prepares portable test products without running tests, using --build-for-testing together with --test-products-path. A second command runs those previously prepared products with --test-products-path and --simulator-name. Separating preparation from execution is the right call for agent workflows, because the expensive compile happens once and the agent can re-run tests against the same artefacts. The README does not state what the test products directory contains beyond the .xctestproducts extension, so treat that as an implementation detail to inspect rather than a documented contract.
One documented default is worth noting: XcodeBuildMCP requests that xcodebuild skip macro validation, to avoid errors when building projects that use Swift Macros. That is a sensible default for agent loops, and also a behaviour you should be aware of if your project relies on macro validation for correctness.
Getting it running: install, init and upgrade
Two install paths are documented. Homebrew users run brew tap getsentry/xcodebuildmcp followed by brew install xcodebuildmcp. npm users on Node.js 18 or later run npm install -g xcodebuildmcp@latest. Either way, xcodebuildmcp --help verifies the install. Clients that cannot manage a global binary can start the server on demand with npx -y xcodebuildmcp@latest mcp.
The README points to drop-in configuration snippets for Cursor, Claude Code and Codex on the MCP Clients docs page rather than reproducing them inline, which is the right place for config that changes per client. Requirements are stated plainly: macOS 14.5 or later, Xcode 16.x or later, and Node.js 18.x or later (not required for the Homebrew route).
There are two optional agent skills. The MCP Skill primes an agent on how to use the server's tools and is described as optional when using the MCP server. The CLI Skill primes an agent on navigating the CLI and is recommended when using the CLI. You install them with xcodebuildmcp init, or npx -y xcodebuildmcp@latest init without a global binary. Upgrades are handled in place with xcodebuildmcp upgrade --check followed by xcodebuildmcp upgrade --yes.
Where XcodeBuildMCP is the wrong tool
Device tools require code signing to be configured in Xcode, per the README's notes. That is a real boundary, not a footnote. If your team has not set up signing, or signs through a separate pipeline, the device-facing portion of the toolset is unavailable until that changes, and no amount of agent prompting fixes it.
The platform requirements rule out a large class of users. macOS 14.5 and Xcode 16.x mean Linux CI is out, and so is any Mac stuck on an older toolchain. Teams that build Apple targets with Bazel or Tuist, or that drive builds through a custom script, will find the tool's arguments assume an .xcodeproj or workspace and a scheme. The README does not claim support for those build systems, and nothing in the supplied material suggests it exists.
There is also a telemetry consideration. The project states it uses Sentry for internal runtime error telemetry, with details and opt-out instructions on a separate Privacy & Telemetry page. The README does not reproduce the opt-out mechanism, so if your environment prohibits outbound error reporting, resolve that before deployment rather than after.
How it differs from driving xcodebuild through a shell tool
The obvious alternative is giving an agent a general shell tool and letting it call xcodebuild directly, which is what most teams do first. The difference is in what the agent has to know. With a shell tool, the agent must recall flag names, destination syntax and the ordering rules that xcodebuild enforces, and it must parse unstructured output to decide whether a build succeeded. With XcodeBuildMCP, those decisions are baked into named tools with typed arguments, and the CLI gives a human the same interface for verification.
The trade-off runs the other way too. A shell tool covers anything the agent can express; XcodeBuildMCP covers the operations the project has chosen to expose. If your build needs an unusual xcodebuild flag that no tool argument maps to, you are back to a shell. The CLI Skill exists precisely because the CLI surface is broad enough that an agent benefits from being told how to move around it, which is a signal that the toolset is not trivially small.
Licence, maintenance and what the release cadence tells you
The project is MIT licensed, with third-party notices split across a THIRD_PARTY_LICENSES file and a THIRD_PARTY_PACKAGE_LICENSES.md file for npm attributions. MIT is permissive and imposes no copyleft obligation on your own code, but the bundled dependencies carry their own terms, and those two files are where you check them. This is not legal advice; if the dependency set matters to your organisation, read the notices and get your own review.
The release history supplied shows v2.7.0 in July 2026, preceded by v2.6.2 and v2.6.1 within the same month, with the repository's last push in September 2026 and the project not archived. Patch releases landing close together are normal for a tool tracking Xcode's own churn, and the in-place upgrade command means version drift is cheap to correct. What the material does not show is a compatibility matrix tying XcodeBuildMCP versions to Xcode versions, so pinning a version and testing against your Xcode install is the conservative move.
Editorial conclusion
Adopt XcodeBuildMCP if your agents already work inside Xcode projects on macOS 14.5 or later with Xcode 16.x, and you want build, test and debug steps driven through the MCP tools rather than pasted shell commands. Skip it if your CI runs on Linux, if you build with Bazel or Tuist, or if device work is central and code signing is not configured in Xcode. Before rolling it out, run xcodebuildmcp tools and confirm the exact tool names your client will see, and read the Privacy & Telemetry page so you know whether the Sentry runtime error reporting is acceptable in your environment.
Community notes