XcodeBuildMCP is a dual-mode system that provides comprehensive iOS and macOS development tooling for both AI coding agents and direct command-line usage. The system exposes 77 tools organized into 15 workflows, enabling AI agents and developers to build, test, debug, and manage Xcode projects, iOS simulators, physical devices, and macOS applications through standardized interfaces README.md3-4 package.json74-75 docs/TOOLS.md3
This page provides a high-level overview of the system architecture, component organization, and execution model.
XcodeBuildMCP operates as a unified codebase that exposes two distinct interfaces while sharing all implementation logic README.md10:
| Mode | Entry Point | Interface | Use Case |
|---|---|---|---|
| CLI Mode | xcodebuildmcp <workflow> <tool> | Direct command-line invocation | Human developers, CI/CD, scripting |
| MCP Server Mode | xcodebuildmcp mcp | JSON-RPC over stdio | AI coding agents (Cursor, Claude, VS Code, etc.) |
Both modes:
build/cli.js package.json12-15.xcodebuildmcp/config.yaml) CHANGELOG.md45-49 CHANGELOG.md65-73The following diagram bridges the "Natural Language Space" (User Intent) to the "Code Entity Space" (Implementation) by showing how different interfaces map to core code entities.
Title: Dual-Mode Interface to Code Entity Mapping
Sources: package.json12-15 package.json83-94 README.md10 README.md25-30
XcodeBuildMCP organizes its 77 tools into 15 logical workflow groups docs/TOOLS.md3 Each workflow represents a cohesive set of development activities. By default, only the simulator workflow tools are enabled to optimize the context window for AI agents skills/xcodebuildmcp/SKILL.md22-23
This diagram shows how high-level workflows are translated into specific code execution paths using the manifest-driven discovery system.
Title: Workflow Invocation to Executor Pipeline
Sources: docs/TOOLS.md14-25 docs/TOOLS.md43-47 CHANGELOG.md43-44
| Category | Workflow | Description |
|---|---|---|
| Simulator | simulator | Build, run, test, and manage state for iOS Simulators docs/TOOLS.md43-44 |
| Physical Device | device | Build, install, and launch apps on physical devices docs/TOOLS.md22-23 |
| macOS Apps | macos | Build, run, and test macOS applications docs/TOOLS.md83-84 |
| Debugging | debugging | LLDB attach, breakpoints, and variable inspection docs/TOOLS.md69-70 |
| Coverage | coverage | Per-target summaries and function-level coverage docs/TOOLS.md14-15 |
| Project Mgmt | project-discovery | Find projects, list schemes, and inspect settings docs/TOOLS.md109-110 |
| Swift Package | swift-package | Build, run, and test SPM projects docs/TOOLS.md144-145 |
| UI Automation | ui-automation | Coordinates-based gestures and hardware buttons docs/TOOLS.md158-159 |
| Sim Management | simulator-management | Boot, erase, and set simulator environmental options docs/TOOLS.md139-140 |
Sources: docs/TOOLS.md1-170 CHANGELOG.md43-51
XcodeBuildMCP implements a tiered configuration hierarchy with the following precedence CHANGELOG.md24:
session_set_defaults tool CHANGELOG.md24.xcodebuildmcp/config.yaml file CHANGELOG.md24XCODEBUILDMCP_WORKSPACE_PATH, XCODEBUILDMCP_SCHEME, and XCODEBUILDMCP_PLATFORM CHANGELOG.md19-21Named profiles enable context switching for monorepos, allowing the CLI and agents to switch between different project/scheme/simulator configurations CHANGELOG.md83-84 CHANGELOG.md127-128:
Sources: CHANGELOG.md19-24 CHANGELOG.md86-101
The system provides "Skills" to prime AI agents with instructions on how to use the tools effectively. This includes a session_show_defaults check before any build/run/test action skills/xcodebuildmcp/SKILL.md26
The system bundles the AXe framework (v1.5.2) to enable UI automation package.json5 CHANGELOG.md113 This allows agents to perform gestures (tap, swipe, long press) and inspect view hierarchies with precise coordinates via snapshot_ui docs/TOOLS.md63 docs/TOOLS.md158-165
XcodeBuildMCP includes integrated Sentry error reporting for production reliability, which can be disabled via the XCODEBUILDMCP_SENTRY_DISABLED environment variable server.json41-49 package.json86
Sources: skills/xcodebuildmcp/SKILL.md1-30 docs/TOOLS.md158-170 server.json41-49