This page introduces XcodeBuildMCP: what it is, the problems it solves, its two primary operation modes, the platforms it targets, and a high-level map of the codebase structure. For installation steps, see Getting Started. For a complete tool listing, see Complete Tool Catalog. For architecture details, see Architecture.
XcodeBuildMCP is a Model Context Protocol (MCP) server and command-line interface that exposes Apple platform development operations — building, testing, running, debugging, and UI automation — as structured, machine-callable tools. It is the bridge between AI coding agents (or terminal scripts) and the Apple toolchain.
From package.json63:
"XcodeBuildMCP is a Model Context Protocol server that provides tools for Xcode project management, simulator management, and app utilities."
It ships as a single npm package (xcodebuildmcp) with two usable surfaces:
| Surface | Invocation | Transport | Primary Consumer |
|---|---|---|---|
| MCP server | xcodebuildmcp mcp | JSON-RPC over stdio | AI agents (Claude, Cursor, Codex, VS Code) |
| CLI | xcodebuildmcp <workflow> <tool> | Terminal I/O | Developers, scripts, CI |
Both surfaces share the same underlying tool implementations, configuration system, and background daemon.
Sources: README.md1-10 package.json1-15 server.json1-20
Without XcodeBuildMCP, AI agents must resort to generating ad-hoc shell commands against xcodebuild, xcrun simctl, and lldb. This leads to:
xcodebuild output is verbose and difficult to parse for error summarization.XcodeBuildMCP addresses these by providing:
Sources: README.md317-355 CHANGELOG.md49-100
| Requirement | Minimum Version |
|---|---|
| macOS | 14.5 |
| Xcode | 16.x |
| Node.js | 18.x (not required for Homebrew install) |
Build targets supported:
xcodebuild + xcrun simctl)xcodebuild + USB/Wi-Fi)xcodebuild)swift build/swift test)Sources: README.md288-293 package.json53-62
Started with xcodebuildmcp mcp. The process communicates over stdio using JSON-RPC as defined by the MCP protocol. AI agent clients (Cursor, Claude Code, Codex, VS Code) connect to it and call its registered tools by name.
The MCP server is bootstrapped through src/index.ts, which calls createServer() and then bootstrapServer() from src/server/. Tool registration is driven by YAML manifests in manifests/tools/ and manifests/workflows/.
All tools are also accessible directly from the terminal. The CLI is the xcodebuildmcp binary defined in package.json12-15:
"bin": {
"xcodebuildmcp": "build/cli.js",
"xcodebuildmcp-doctor": "build/doctor-cli.js"
}
CLI commands follow the pattern xcodebuildmcp <workflow> <tool> [options]. For example:
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
The mcp subcommand is what starts the MCP server: xcodebuildmcp mcp.
For a detailed comparison, see Dual-Mode Design.
Sources: README.md326-344 package.json8-15
The following diagram shows the major runtime components and their relationships, mapping system names to source files and code constructs.
Diagram: Runtime Components and Entry Points
Sources: README.md1-10 package.json8-15 src/mcp/resources/simulators.ts1-60
The following table maps the major directories to their roles.
| Path | Role |
|---|---|
src/cli.ts | CLI entry point; parses yargs commands, routes to tools or MCP server |
src/index.ts | MCP server entry point; calls createServer() |
src/server/ | createServer(), bootstrapServer() — MCP server lifecycle |
src/mcp/tools/ | Tool implementation modules, grouped by workflow |
src/mcp/resources/ | MCP resource handlers (simulators, doctor, etc.) |
src/utils/tool-registry.ts | applyWorkflowSelectionFromManifest() — manifest loading and tool registration |
src/utils/config-store.ts | ConfigStore — resolves env vars, YAML config, and defaults |
src/utils/session-store.ts | SessionStore — runtime defaults and named profiles |
src/utils/typed-tool-factory.ts | createSessionAwareTool(), createTypedTool() — tool construction helpers |
src/runtime/tool-invoker.ts | DefaultToolInvoker — routes tool calls to direct exec or daemon |
src/utils/execution/ | CommandExecutor, FileSystemExecutor, defaultExecutor |
src/visibility/ | Predicate system for runtime tool visibility |
src/utils/debugger/ | DebuggerManager, LLDB CLI backend, DAP backend |
manifests/tools/ | YAML definitions for every tool |
manifests/workflows/ | YAML definitions grouping tools into workflows |
bundled/ | Bundled AXe binary and frameworks |
skills/ | Agent skill files installed via xcodebuildmcp init |
scripts/ | Build, release, and packaging scripts |
docs/ | User-facing documentation |
Sources: package.json46-52 README.md346-356
Tools are organized into 13 named workflow groups. Clients can enable only the groups they need, reducing MCP context window size.
Diagram: Workflow Groups and Apple Tool Dependencies
Sources: README.md1-360 CHANGELOG.md49-100 server.json22-60
XcodeBuildMCP has two configuration layers that both control workflow selection and session defaults.
| Layer | Location | Precedence |
|---|---|---|
| Project config file | .xcodebuildmcp/config.yaml | Higher |
| Environment variables | Shell environment | Lower |
Key environment variables:
| Variable | Effect |
|---|---|
XCODEBUILDMCP_ENABLED_WORKFLOWS | Comma-separated list of workflows to activate |
INCREMENTAL_BUILDS_ENABLED | Enable xcodemake incremental build integration |
XCODEBUILDMCP_SENTRY_DISABLED | Opt out of error telemetry |
XCODEBUILDMCP_DEBUG | Enable verbose debug logging |
For the full configuration reference, see Configuration and Environment Variables.
Sources: server.json21-60 CHANGELOG.md63-79
| Package | Role |
|---|---|
@modelcontextprotocol/sdk | MCP protocol implementation (server, stdio transport) |
zod | Schema validation for tool input parameters |
yargs | CLI argument parsing |
yaml | Parsing .xcodebuildmcp/config.yaml and manifest files |
@sentry/node | Internal error telemetry (opt-out available) |
chokidar | File watching (used in daemon and Xcode IDE bridge) |
uuid | Session and daemon identifier generation |
Sources: package.json72-82
| Goal | Page |
|---|---|
| Install and connect a client | Getting Started |
| Understand the MCP server vs. CLI in detail | Dual-Mode Design |
| See how tools and workflows are registered | Tool Registry and Workflow System |
| Browse all available tools | Complete Tool Catalog |
| Configure the project config file | Configuration |
| Troubleshoot a problem | Troubleshooting |
| Add a new tool | Tool Development Guide |
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.