This document provides a high-level introduction to XcodeBuildMCP, explaining what it is, its core capabilities, and how its major components fit together. For detailed information about specific subsystems, see:
XcodeBuildMCP is a Model Context Protocol (MCP) server that exposes Apple's Xcode development ecosystem to AI assistants and other MCP clients. It bridges the gap between natural language interactions and Apple platform development by providing 71 structured tools organized into 13 workflow groups.
The server implements the MCP specification version 2025-09-16 and is identified by the name com.xcodebuildmcp/XcodeBuildMCP. It operates as a stdio-based transport server, accepting JSON-RPC 2.0 messages from MCP clients such as Claude Desktop, Cursor, VS Code with Continue, and other compatible environments.
Sources: README.md1-110 server.json1-65 package.json1-101
XcodeBuildMCP provides comprehensive automation across the Apple development workflow:
| Capability | Tools | Description |
|---|---|---|
| Build Automation | 24 tools | Build for iOS/macOS/watchOS/tvOS/visionOS on simulators, devices, and native Mac targets |
| Testing | 8 tools | Execute XCTest suites with xcresult parsing and structured result formatting |
| Device Management | 7 tools | Interact with physical Apple devices over USB and WiFi |
| Simulator Management | 17 tools | Boot, configure, and manage iOS/watchOS/tvOS/visionOS simulators |
| UI Automation | 11 tools | Interact with running apps via AXe binary integration (tap, swipe, type, screenshot) |
| Debugging | 8 tools | Attach LLDB debugger with DAP protocol support, set breakpoints, inspect variables |
| Project Management | 7 tools | Discover projects, scaffold new apps from templates, inspect build settings |
| Swift Package Manager | 6 tools | Build, test, and run Swift packages |
| App Lifecycle | 6 tools | Install, launch, and stop applications on all platforms |
| Log Capture | 4 tools | Stream and capture device/simulator logs with session management |
| Utilities | 3 tools | Clean build artifacts, run system diagnostics, manage session defaults |
The server reduces context window usage by 27% compared to exposing 81 individual tools through parameter consolidation and workflow-based organization.
Sources: README.md1-110 CHANGELOG.md41 Diagram 2 from provided architecture diagrams
XcodeBuildMCP requires the following runtime environment:
| Component | Version | Purpose |
|---|---|---|
| macOS | 14.5+ | Host operating system |
| Xcode | 16.x+ | Apple development toolchain and xcodebuild command |
| Node.js | 18.x+ | JavaScript runtime for MCP server |
| AXe | 1.1.0+ | UI automation binary (optional, required for UI tools) |
The server uses xcodebuild and xcrun simctl as primary execution interfaces to Apple's development tools. UI automation tools require the external AXe binary, installed via brew install cameroncooke/axe/axe. When distributed via Smithery, AXe must be installed separately due to packaging limitations.
Sources: README.md84-88 README.md16-17
The following diagram shows the main components of XcodeBuildMCP and their relationships to actual code entities:
Sources: package.json13-16 server.json1-65
The server bootstrap process follows this sequence, referencing actual code paths:
The createPluginDiscoveryPlugin() function in src/core/plugin-discovery-plugin.ts runs at build time via esbuild, scanning the filesystem for workflow directories in src/mcp/tools/ and resource files in src/mcp/resources/ It generates src/core/generated-plugins.ts and src/core/generated-resources.ts containing typed loader functions that import tools and resources dynamically at runtime.
Sources: package.json13-21 Diagram 5 from provided architecture diagrams
The tool system maps workflow directories to runtime tool registration:
Each workflow directory in src/mcp/tools/ exports a workflow constant containing metadata and an array of tool definitions. Tools follow a consistent structure with Zod schema validation, a logic function, and optional session awareness. The system supports selective workflow loading via the XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable, allowing clients to reduce startup tool count.
Sources: server.json35-40 Diagram 2 and Diagram 5 from provided architecture diagrams
XcodeBuildMCP is distributed through multiple channels:
| Channel | Identifier | Installation Command |
|---|---|---|
| NPM | [email protected] | npm install xcodebuildmcp |
| Smithery | cameroncooke/xcodebuildmcp | npx @smithery/cli install cameroncooke/xcodebuildmcp --client <client> |
| MCP Registry | DNS-authenticated entry | Via compatible MCP client configuration |
| GitHub Releases | Tag: v1.15.1 | Download .tgz from releases |
The package structure includes:
build/ - Compiled TypeScript output with index.js and doctor-cli.js entry pointsbundled/ - AXe binary and frameworks for UI automation (not included in Smithery bundles)plugins/ - Additional runtime pluginsThe recommended installation method is Smithery for seamless client integration. Manual installation requires editing the MCP client configuration file (typically claude_desktop_config.json, cursor_config.json, or similar) to specify the server command and environment variables.
Sources: README.md8-81 package.json46-50 Diagram 4 from provided architecture diagrams
The server behavior is controlled via environment variables defined in server.json22-61:
| Variable | Type | Default | Description |
|---|---|---|---|
INCREMENTAL_BUILDS_ENABLED | boolean | false | Enable xcodemake for incremental builds instead of full xcodebuild |
XCODEBUILDMCP_ENABLED_WORKFLOWS | string | "" | Comma-separated workflow names to load (e.g., "simulator,device") |
XCODEBUILDMCP_SENTRY_DISABLED | boolean | false | Disable Sentry error telemetry collection |
XCODEBUILDMCP_DEBUG | boolean | false | Enable verbose debug logging to stderr |
Additional template override variables exist for project scaffolding (documented in Configuration and Environment Variables).
Sources: server.json22-61 README.md94-96
XcodeBuildMCP employs several architectural patterns that inform its implementation:
1. Dependency Injection for Testability
The CommandExecutor and FileSystemExecutor interfaces in src/utils/command-executor.ts and src/utils/file-system-executor.ts abstract all system interactions. Tool logic functions receive these as injected dependencies, enabling test safety through mock implementations that prevent actual command execution during tests.
2. Session-Aware Parameter Management
The SessionStore class in src/core/session-store.ts maintains default parameter values that tools can query and merge with explicit parameters. The session-set-defaults tool allows clients to configure defaults once (e.g., projectPath, scheme, simulatorId) and reuse them across tool calls, reducing repetition and token usage.
3. Plugin Discovery via Build-Time Code Generation
Rather than manual tool registration, the system scans src/mcp/tools/ at build time via an esbuild plugin, generating typed loader maps. This convention-over-configuration approach eliminates registration boilerplate and ensures type safety.
4. Error Classification for Privacy
Error handling distinguishes between domain errors (user/configuration issues) and server errors (internal bugs). Only server errors are reported to Sentry, protecting user privacy and reducing noise. Domain errors return actionable guidance in tool responses.
Sources: src/utils/command-executor.ts src/core/session-store.ts src/core/plugin-discovery-plugin.ts Diagram 6 from provided architecture diagrams
Current version: 1.15.1 (as of package.json and server.json)
The project maintains separate version numbers for:
v1.0.8 (tracked in package.json iOSTemplateVersion)v1.0.5 (tracked in package.json macOSTemplateVersion)Release artifacts are published to NPM with tags (latest, beta, alpha, rc) and uploaded to GitHub releases. Sentry releases track deployed versions with sourcemaps for error tracking. The complete version history and feature additions are documented in Versioning and Changelog.
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.