This document provides a high-level introduction to XcodeBuildMCP, explaining its dual-mode architecture, tool organization, and core subsystems. For installation instructions, see Getting Started. For complete tool listings, see Complete Tool Catalog. For configuration details, see Configuration Reference.
XcodeBuildMCP is a dual-interface system that exposes Apple development capabilities through both a command-line interface (CLI) and a Model Context Protocol (MCP) server. It provides 81 canonical tools organized into 16 workflow groups for building, testing, debugging, and deploying iOS, macOS, watchOS, tvOS, and visionOS applications.
The system serves two primary use cases:
MCP Server Mode: Enables AI coding assistants (Cursor, VS Code, Claude Code, Codex CLI, Xcode agents) to programmatically manage Xcode projects, simulators, devices, and debugging sessions via the MCP protocol over stdio transport.
CLI Mode: Provides direct terminal access to the same capabilities for scripting, CI workflows, and manual development tasks.
Both modes share the same underlying implementation—the CLI invokes the same tool logic as MCP clients, ensuring functional parity.
Sources: README.md1-10 package.json1-15 docs/TOOLS.md1-5
XcodeBuildMCP operates in two distinct modes controlled by command invocation:
| Mode | Invocation | Transport | Use Case |
|---|---|---|---|
| MCP Server | xcodebuildmcp mcp | stdio (JSON-RPC) | AI agent integration |
| CLI | xcodebuildmcp <workflow> <tool> | Direct execution | Terminal/scripting |
The MCP server starts via cluster-src/index.ts, which initializes a McpServer instance from @modelcontextprotocol/sdk, registers tools and resources, and listens on stdio. The CLI application starts via cluster-src/cli/commands/init.ts using yargs, parsing workflow and tool names to invoke the same underlying modules.
For stateful operations (log capture, debugging sessions, video recording), the CLI spawns a per-workspace background daemon that auto-starts when needed and shuts down after idle. The MCP server handles state directly in the server process.
Sources: README.md336-356 package.json12-15 Diagram 1 from system architecture
Sources: Diagram 1 (High-Level System Architecture), package.json12-15 README.md338-355
Tools are organized into 16 workflow groups defined in YAML manifests at manifests/workflows/*.yaml. Each workflow has an ID (e.g., simulator, device, debugging) and lists constituent tool IDs. The ToolRegistry class in cluster-src/utils/toolregistry.ts loads these manifests, evaluates predicates to determine which workflows apply to the current runtime context, and registers only enabled tools with the MCP server or CLI command tree.
By default, only the simulator workflow loads to minimize context window usage for AI clients. Additional workflows require explicit enablement via .xcodebuildmcp/config.yaml or the XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable.
Each tool manifest (manifests/tools/*.yaml) defines:
mcp/tools/simulator/build_run_sim)hideWhenXcodeAgentMode)readOnlyHint, destructiveHint, idempotent)Sources: docs/TOOLS.md1-23 Diagram 3 (Configuration Loading and Tool Registration), manifests/tools/build_run_sim.yaml1-25
The SessionStore class maintains per-profile defaults for projectPath, scheme, simulatorName, deviceId, configuration, and custom environment variables. Session defaults reduce parameter burden—instead of specifying project, scheme, and simulator on every tool call, these are configured once via session_set_defaults and persist across the session.
Profiles enable switching between different project contexts (e.g., iOS vs watchOS development) without reconfiguring. The active profile is tracked in memory, and defaults can optionally persist to .xcodebuildmcp/config.yaml via the persist: true flag.
When a tool handler executes, the createSessionAwareTool factory in cluster-src/utils/typedtoolfactory.ts merges explicit arguments with session defaults, performs deep merging for environment variables, validates mutual exclusivity constraints (e.g., projectPath vs workspacePath), and passes the merged parameters to the tool logic.
Sources: README.md19 CHANGELOG.md19 Diagram 2 (Request Flow from Client to External Tools)
The CommandExecutor interface in cluster-src/utils/commandexecutor.ts abstracts process spawning and file system operations. Production code uses RealCommandExecutor, which wraps Node.js child_process.spawn and fs operations. Test code injects MockCommandExecutor to avoid real system calls.
This abstraction enables:
xcodebuild invocations in unit tests)Build and test operations use executeXcodeBuildCommand from cluster-src/utils/buildutils.ts which implements intelligent strategy selection between direct xcodebuild invocation and incremental builds via xcodemake (when enabled), with automatic fallback on non-compiler errors.
Sources: Diagram 2 (Request Flow), Diagram 4 (Build and Test Execution Pipeline)
XcodeBuildMCP organizes its 81 canonical tools into 16 workflow groups. Only simulator, project-discovery, session-management, and doctor load by default. Others require explicit enablement.
| Workflow | ID | Tools | Default | Purpose |
|---|---|---|---|---|
| iOS Simulator Development | simulator | 23 | ✓ | Build, run, test, install, launch on iOS/watchOS/tvOS/visionOS simulators |
| iOS Device Development | device | 16 | ✗ | Build, test, deploy to physical Apple devices (iPhone, iPad, Watch, TV, Vision Pro) |
| macOS Development | macos | 13 | ✗ | Build, run, test native macOS applications |
| LLDB Debugging | debugging | 8 | ✗ | Attach debugger, set breakpoints, inspect variables/stack |
| Log Capture | logging | 4 | ✗ | Stream and capture logs from simulators and devices |
| UI Automation | ui-automation | 11 | ✗ | Gestures, screenshots, UI hierarchy inspection, accessibility testing |
| Swift Package Development | swift-package | 8 | ✗ | Build, run, test Swift Package Manager projects |
| Project Discovery | project-discovery | 5 | ✓ | Find projects/workspaces, list schemes, inspect build settings |
| Session Management | session-management | 5 | ✓ | Set/clear/show session defaults and profiles |
| Simulator Management | simulator-management | 8 | ✓ | Boot, erase, configure simulators (location, appearance, status bar) |
| Xcode IDE Integration | xcode-ide | 5 | ✗ | Proxy tools from Xcode 26.3+ built-in MCP bridge |
| Project Scaffolding | project-scaffolding | 2 | ✗ | Generate iOS/macOS projects from templates |
| Code Coverage | coverage | 2 | ✗ | Per-target and function-level coverage from xcresult bundles |
| Build Utilities | utilities | 1 | ✓ | Clean build products |
| MCP Doctor | doctor | 1 | ✓ | Environment diagnostics and dependency verification |
| Workflow Discovery | workflow-discovery | 1 | ✓ | Runtime workflow management (MCP mode only) |
Total: 81 canonical tools, 113 total tools (due to cross-workflow references where a tool appears in multiple workflows).
Sources: docs/TOOLS.md5-226 README.md3
Sources: docs/TOOLS.md5-23 Diagram 3 (Configuration Loading), server.json35-39
The tool registry uses predicate evaluation to dynamically filter workflows and tools based on runtime context. Predicates (defined in cluster-src/utils/predicates.ts) check conditions like:
hideWhenXcodeAgentMode: Hides tools when running inside Xcode's agent environment (to avoid redundant functionality with Xcode's built-in MCP bridge)This reduces the tool count exposed to AI clients, minimizing context window usage while maintaining full CLI access.
Sources: Diagram 3, manifests/tools/build_run_sim.yaml7-8
The createSessionAwareTool factory performs multi-layer validation and transformation:
env objects with TEST_RUNNER_* prefixing for test toolsThis enables AI agents to issue minimal tool calls (e.g., build_run_sim with no arguments) once session defaults are established via session_set_defaults.
Sources: Diagram 2 (Request Flow), CHANGELOG.md20
When INCREMENTAL_BUILDS_ENABLED=true or configured in .xcodebuildmcp/config.yaml, the build system attempts to use xcodemake (a Make-based incremental build tool) before falling back to xcodebuild. The strategy selector in cluster-src/utils/buildutils.ts:
xcodemake availabilitypreferXcodebuild flagxcodemake on first buildmake for subsequent buildsxcodebuild on non-compiler errors with actionable hintsThis significantly reduces rebuild times for large projects.
Sources: Diagram 4 (Build and Test Execution Pipeline), server.json22-33 CHANGELOG.md239-241
Test tools (test_sim, test_device, test_macos) create temporary directories for xcresult bundles, normalize environment variables with TEST_RUNNER_* prefixes, and parse structured test results via parseXcresultBundle in cluster-src/utils/xcresult.ts
Critical edge case handling:
totalTestCount is zero, return raw output (exposing build failures) instead of an empty test summarySources: Diagram 4, CHANGELOG.md11-12 docs/TOOLS.md14-18
The Homebrew distribution bundles a complete Node.js runtime, compiled application code, the AXe UI automation binary with signed frameworks, and agent skill definitions into a self-contained tarball. The release workflow (.github/workflows/release.yml) builds for both arm64 and x64, verifies each build, combines them into a universal binary via lipo, and updates the Homebrew formula.
The verification script (scripts/verify-portable-install.sh) validates directory structure, wrapper executables, code signatures, framework presence, and (when host architecture matches) actual command execution.
Sources: Diagram 5 (Release and Distribution Workflow), README.md12-33
The server exposes 5 MCP resources for AI clients to query without tool invocations:
devices://list: Connected physical devicessimulators://list: Available iOS/watchOS/tvOS/visionOS simulatorssession://status: Current session defaults and active profilediagnostics://doctor: Environment info and dependency statusxcode-ide://state: Xcode IDE MCP bridge connection stateResources are read-only and registered via server.setRequestHandler in cluster-src/index.ts
Sources: Diagram 1, CHANGELOG.md174
XcodeBuildMCP requires:
Installation methods:
Homebrew (system-wide portable binary):
npm (global Node.js package):
npx (zero-install MCP server):
Client-specific setup instructions for Cursor, VS Code, Claude Code, Codex CLI, Windsurf, Kiro, Trae, and Xcode agents are documented in README.md52-283
Sources: README.md8-304 Diagram 5
The system uses a single-source-of-truth pattern where YAML manifests define both runtime tool behavior and generated documentation. The scripts/update-tools-docs.ts script processes manifests to generate:
A validation script (scripts/check-docs-cli-commands.js) extracts CLI commands from documentation and validates them against the runtime tool catalog, catching documentation drift.
Agent skills are installed via xcodebuildmcp init, which auto-detects AI clients (Claude Code, Cursor, Codex) and copies skill files to .claude/skills/, .agents/skills/, or .codex/skills/ with conflict resolution and profile management.
Sources: Diagram 6 (Documentation and Tool Definition System), docs/SKILLS.md1-43 package.json37-39
Refresh this wiki