This page provides quick-lookup reference material for XcodeBuildMCP's tools, configuration options, and environment variables. It serves as a comprehensive index for developers and users who need to find specific parameter names, configuration keys, or tool capabilities without reading full documentation.
For detailed usage examples and workflows, see Getting Started. For architectural details about how these systems work internally, see Architecture. For tool-by-tool documentation with examples, see Tools and Workflows.
The following diagram maps configuration sources to their corresponding code entities and resolution order.
Sources: src/core/config/config-store.ts src/core/config/project-config.ts server.json21-60 docs/GETTING_STARTED.md66-72
This diagram shows how tools are organized in the codebase and how the manifest system loads them.
Sources: manifests/workflows/ manifests/tools/ src/core/manifest/manifest-loader.ts src/core/tools/tool-registry.ts plugins/tools/
This diagram shows how environment variables are processed and where they are consumed.
Sources: src/core/config/config-store.ts src/core/observability/sentry.ts src/core/resource-root.ts server.json21-60
The following diagram shows the structure of .xcodebuildmcp/config.yaml and maps each key to its TypeScript type definition.
Sources: src/core/config/project-config.ts src/core/config/config-types.ts src/core/session/session-types.ts docs/CONFIGURATION.md
The following table shows the 15 workflow groups and their characteristics. For a complete alphabetical tool catalog, see Complete Tool Catalog.
| Workflow ID | Tool Count | Default Enabled | Auto-Include | Description |
|---|---|---|---|---|
simulator | 21 | ✅ Yes | No | iOS/watchOS/tvOS/visionOS simulator build, run, test, logs, video |
session-management | 5 | No | ✅ Yes | Session defaults and profile management |
device | 14 | No | No | Physical device deployment, testing, logs |
ui-automation | 11 | No | No | AXe-powered tap, swipe, text input, UI inspection |
debugging | 8 | No | No | LLDB attach, breakpoints, variables, call stack |
macos | 11 | No | No | macOS app build, run, test |
logging | 4 | No | No | Simulator and device log capture and streaming |
simulator-management | 8 | No | No | Boot, list, open, erase simulators |
swift-package | 6 | No | No | Swift Package Manager build, test, run |
project-discovery | 5 | No | No | Discover projects, list schemes, bundle IDs |
utilities | 1 | No | No | Clean build products |
project-scaffolding | 2 | No | No | Create new projects from templates |
doctor | 1 | No | Conditional | System diagnostics (requires debug=true) |
workflow-discovery | 1 | No | No | Runtime workflow management (experimental) |
xcode-ide | 5 | No | No | Xcode 26.3 MCP bridge gateway |
Total: 79 tools across 15 workflows
Sources: README.md1-354 package.json1-107 Diagram 2 from system architecture overview
| Key | Value |
|---|---|
| Current Version | 2.0.7 |
| MCP Name | com.xcodebuildmcp/XcodeBuildMCP |
| npm Package | xcodebuildmcp |
| Homebrew Tap | getsentry/xcodebuildmcp |
| Repository | https://github.com/getsentry/XcodeBuildMCP |
| AXe Version | 1.4.0 |
| iOS Template Version | v1.0.8 |
| macOS Template Version | v1.0.5 |
| Node.js Requirement | >=18.x |
| macOS Requirement | >=14.5 |
| Xcode Requirement | >=16.x |
Sources: package.json1-107 .axe-version1 README.md288-293
| Method | Command | Node.js Required | Platform |
|---|---|---|---|
| Homebrew | brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp | No | macOS (universal binary) |
| npm (global) | npm install -g xcodebuildmcp@latest | Yes | macOS |
| npx (on-demand) | npx -y xcodebuildmcp@latest | Yes | macOS |
Distribution Artifacts:
Sources: README.md8-286 docs/GETTING_STARTED.md19-64
The following table provides quick-reference configuration snippets for common MCP clients. All examples use npx; replace with "command": "xcodebuildmcp", "args": ["mcp"] if installed via Homebrew.
| Client | Configuration File | Example |
|---|---|---|
| Cursor (project) | .cursor/mcp.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Cursor (global) | ~/.cursor/mcp.json | {"mcpServers": {"XcodeBuildMCP": {"command": "/bin/zsh", "args": ["-lc", "cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@latest mcp"]}}} |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| VS Code | Settings JSON | "mcp": {"servers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Kiro (workspace) | .kiro/settings/mcp.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Kiro (user) | ~/.kiro/settings/mcp.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Trae | ~/Library/Application Support/Trae/User/mcp.json | {"mcpServers": {"XcodeBuildMCP": {"command": "npx", "args": ["-y", "xcodebuildmcp@latest", "mcp"]}}} |
| Codex CLI | ~/.codex/config.toml | [mcp_servers.XcodeBuildMCP]command = "npx"args = ["-y", "xcodebuildmcp@latest", "mcp"] |
| Claude Code CLI | Command line | claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp |
| Xcode (Codex Agent) | .codex/config.toml (project root) | [mcp_servers.XcodeBuildMCP]command = "/bin/zsh"args = ["-lc", "PATH=...; npx -y xcodebuildmcp@latest mcp"]enabled = truetool_timeout_sec = 10000 |
| Xcode (Claude Code) | ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json | "mcpServers": {"XcodeBuildMCP": {"command": "/bin/zsh", "args": ["-lc", "PATH=...; npx -y xcodebuildmcp@latest mcp"]}} |
Sources: README.md54-283 docs/GETTING_STARTED.md74-143
| Subcommand | Description | Example |
|---|---|---|
mcp | Start MCP server | xcodebuildmcp mcp |
tools | List available tools | xcodebuildmcp tools |
workflows | List available workflows | xcodebuildmcp workflows |
daemon status | Check daemon status | xcodebuildmcp daemon status |
daemon start | Start daemon | xcodebuildmcp daemon start |
daemon stop | Stop daemon | xcodebuildmcp daemon stop |
<workflow> <tool> | Invoke a tool | xcodebuildmcp simulator build --scheme MyApp |
<workflow> --help | Show workflow tools | xcodebuildmcp simulator --help |
<workflow> <tool> --help | Show tool parameters | xcodebuildmcp simulator build --help |
Sources: README.md320-339 docs/CLI.md src/cli/cli.ts
This table maps high-level concepts to their primary implementation files for quick code navigation.
| Concept | Primary File(s) | Key Classes/Functions |
|---|---|---|
| Tool Registry | src/core/tools/tool-registry.ts | ToolRegistry, registerWorkflows(), getToolDefinition() |
| Configuration Resolution | src/core/config/config-store.ts | ConfigStore, resolveFromLayers() |
| Session Management | src/core/session/session-store.ts | SessionStore, setDefaults(), useProfile() |
| Tool Invocation | src/core/tools/tool-invoker.ts | ToolInvoker, invokeTool(), postProcessToolResponse() |
| Background Daemon | src/daemon/daemon-manager.ts | DaemonManager, ensureDaemonRunning() |
| Command Execution | src/core/execution/command-executor.ts | CommandExecutor, executeCommand() |
| Manifest Loading | src/core/manifest/manifest-loader.ts | ManifestLoader, loadWorkflowManifest(), loadToolManifest() |
| Project Config | src/core/config/project-config.ts | ProjectConfig, loadProjectConfig(), saveProjectConfig() |
| Bootstrap (MCP) | src/cli/server-bootstrap.ts | bootstrapMCPServer() |
| Bootstrap (CLI) | src/cli/cli-bootstrap.ts | bootstrapCLI() |
| Resource Root | src/core/resource-root.ts | getResourceRoot(), detectResourceRoot() |
| Sentry Integration | src/core/observability/sentry.ts | initSentry(), captureError() |
| Logger | src/core/observability/logger.ts | Logger, log(), error() |
| Validation Utilities | src/core/validation/ | validateRequiredParam(), validateAllowedValues() |
| NextSteps Synthesis | src/core/tools/tool-invoker.ts | buildTemplateNextSteps(), mergeTemplateAndResponseNextSteps() |
Sources: src/core/ src/cli/ src/daemon/
| Dependency | Version | Purpose |
|---|---|---|
@modelcontextprotocol/sdk | ^1.25.1 | MCP protocol implementation |
@sentry/node | ^10.38.0 | Error tracking and metrics |
zod | ^4.0.0 | Schema validation |
yaml | ^2.4.5 | Config file parsing |
yargs | ^17.7.2 | CLI argument parsing |
chokidar | ^5.0.0 | File watching (log capture) |
uuid | ^11.1.0 | Unique ID generation |
bplist-parser | ^0.3.2 | Binary plist parsing |
Dev Dependencies (selected):
typescript ^5.8.2vitest ^3.2.4tsup ^8.5.0eslint ^9.23.0prettier 3.6.2Sources: package.json71-105
| Script | Command | Purpose |
|---|---|---|
| Build | npm run build | Compile TypeScript to JavaScript |
| Test | npm test | Run Vitest test suite |
| Lint | npm run lint | Run ESLint checks |
| Bundle AXe | npm run bundle:axe | Download and bundle AXe framework |
| Package (macOS) | npm run package:macos | Create portable macOS binary |
| Release | scripts/release.sh | Version bump, changelog, git tag |
| Doctor | npm run doctor | Run system diagnostics |
| Update Docs | npm run docs:update | Regenerate tool documentation |
Sources: package.json16-45 scripts/
| Metric Name | Type | Description |
|---|---|---|
tool.invocation.count | Counter | Total tool invocations |
tool.invocation.duration_ms | Histogram | Tool execution time |
daemon.lifecycle | Event | Daemon start/stop events |
bootstrap.duration_ms | Histogram | Server startup time |
Error Hierarchy:
XcodeBuildMCPError (base)
ValidationErrorSystemErrorSimulatorErrorDeviceErrorAxeErrorDependencyErrorDebuggerErrorSentry Configuration:
XCODEBUILDMCP_SENTRY_DISABLED=trueUSER_HOME_PATH_PATTERN regexSources: src/core/observability/sentry.ts src/core/observability/logger.ts src/core/observability/metrics.ts CHANGELOG.md13
| Aspect | Details |
|---|---|
| Version | 1.4.0 |
| Location | bundled/AXe/ (npm/Homebrew) |
| Binary | bundled/AXe/bin/AXe |
| Framework | bundled/AXe/AXe.framework/ |
| Environment Variable | DYLD_FRAMEWORK_PATH set at runtime |
| Code Signing | Ad-hoc signature applied for portability |
| Download Script | scripts/bundle-axe.sh |
AXe Tools:
snapshot_ui - Capture UI hierarchytap - Tap elements by label/IDswipe - Swipe gesturestype_text - Text inputscreenshot - Capture screenshotsvideo_start / video_stop - Video recordingSources: .axe-version1 scripts/bundle-axe.sh README.md150
For complete listings of all tools, configuration options, and environment variables, see the subsections:
For usage examples and workflows, see Quick Start Examples and Tools and Workflows.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.