Skip to content

Latest commit

 

History

History
329 lines (233 loc) · 9.11 KB

CONFIGURATION.md

File metadata and controls

329 lines (233 loc) · 9.11 KB

Configuration

XcodeBuildMCP reads configuration from a project config file. The config file is optional but provides deterministic, repo-scoped behavior for every session.

Contents

Config file

Create a config file at your workspace root:

<workspace-root>/.xcodebuildmcp/config.yaml

Minimal example:

schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation", "debugging"]

Full example options:

schemaVersion: 1

# Workflow selection
enabledWorkflows: ["simulator", "ui-automation", "debugging"]
experimentalWorkflowDiscovery: false

# Session defaults
disableSessionDefaults: false
sessionDefaults:
  projectPath: "./MyApp.xcodeproj"
  scheme: "MyApp"
  configuration: "Debug"
  simulatorName: "iPhone 16"
  platform: "iOS"
  useLatestOS: true
  arch: "arm64"
  suppressWarnings: true
  derivedDataPath: "./.derivedData"
  preferXcodebuild: false
  bundleId: "io.sentry.myapp"

# Build settings
incrementalBuildsEnabled: false

# Debugging
debug: false
debuggerBackend: "dap"
dapRequestTimeoutMs: 30000
dapLogEvents: false
launchJsonWaitMs: 8000

# UI automation
uiDebuggerGuardMode: "error"
axePath: "/opt/axe/bin/axe"

# Templates
iosTemplatePath: "/path/to/ios/templates"
iosTemplateVersion: "v1.2.3"
macosTemplatePath: "/path/to/macos/templates"
macosTemplateVersion: "v1.2.3"

The schemaVersion field is required and currently only supports 1.

Session defaults

Session defaults allow you to set shared values once (project, scheme, simulator, etc.) that all tools reuse automatically. This reduces token usage and ensures consistent behavior.

Enabling and disabling

Session defaults are enabled by default. To disable them:

disableSessionDefaults: true

When disabled, agents must pass explicit parameters on every tool call (legacy behavior).

Setting defaults from config

Seed defaults at server startup by adding a sessionDefaults block:

sessionDefaults:
  projectPath: "./MyApp.xcodeproj"
  scheme: "MyApp"
  configuration: "Debug"
  simulatorName: "iPhone 16"

Setting defaults from an agent

Agents can call session_set_defaults at runtime. By default these are stored in memory only. To persist them to the config file, the agent sets persist: true.

Session defaults reference

Option Type Description
projectPath string Path to .xcodeproj file. Mutually exclusive with workspacePath.
workspacePath string Path to .xcworkspace file. Takes precedence if both are set.
scheme string Build scheme name.
configuration string Build configuration (e.g., Debug, Release).
simulatorName string Simulator name (e.g., iPhone 16). Mutually exclusive with simulatorId.
simulatorId string Simulator UUID. Takes precedence if both are set.
deviceId string Physical device UUID.
platform string Target platform (e.g., iOS, macOS, watchOS, tvOS, visionOS).
useLatestOS boolean Use the latest available OS version for the simulator.
arch string Build architecture (e.g., arm64, x86_64).
suppressWarnings boolean Suppress compiler warnings in build output.
derivedDataPath string Custom path for derived data.
preferXcodebuild boolean Use xcodebuild instead of the experimental incremental build support (xcodemake). Only applies when incremental builds are enabled. Is designed for agent use to self correct after failed xcodemake build attempts.
bundleId string App bundle identifier.

Mutual exclusivity rules

  • If both projectPath and workspacePath are set, workspacePath wins.
  • If both simulatorId and simulatorName are set, simulatorId wins.

Workflow selection

Workflows determine which tools are available. By default only the simulator workflow is loaded.

enabledWorkflows: ["simulator", "ui-automation", "debugging"]

See TOOLS.md for available workflows and their tools.

To proxy Xcode IDE tools (Xcode 26+ xcrun mcpbridge), enable xcode-ide. See XCODE_IDE_MCPBRIDGE.md.

Experimental workflow discovery

Enables a manage-workflows tool that agents can use to add/remove workflows at runtime.

experimentalWorkflowDiscovery: true

Important

Requires client support for tools changed notifications. At the time of writing, Cursor, Claude Code, and Codex do not support this.

Build settings

Incremental builds

Enable incremental builds to speed up repeated builds:

incrementalBuildsEnabled: true

Important

Incremental builds are experimental and may not work for all projects. Agents can bypass this setting per-call if needed.

Debugging and logging

Debug logging

Enable debug logging and the doctor diagnostic tool:

debug: true

Debugger backend

Select the debugger backend:

debuggerBackend: "dap"  # or "lldb-cli"

Default is dap. Changing this is not generally recommended.

DAP settings

Tune the DAP backend:

dapRequestTimeoutMs: 30000  # default: 30000
dapLogEvents: true          # default: false

Device log capture

Control how long to wait for devicectl JSON output:

launchJsonWaitMs: 8000  # default: 8000

UI automation

Debugger guard

Block UI automation tools when the debugger is paused to prevent failures:

uiDebuggerGuardMode: "error"  # "error" | "warn" | "off"

Default is error.

AXe binary

UI automation and simulator video capture require AXe, which is bundled by default. To use a different version:

axePath: "/opt/axe/bin/axe"

See the AXe repository for more information.

Templates

The scaffold tools pull templates from GitHub. Override the default locations and versions:

iosTemplatePath: "/path/to/ios/templates"
iosTemplateVersion: "v1.2.3"
macosTemplatePath: "/path/to/macos/templates"
macosTemplateVersion: "v1.2.3"

Default templates:

Telemetry

By default, error logs are sent to Sentry. To disable:

# Environment variable only (no config.yaml option)
# XCODEBUILDMCP_SENTRY_DISABLED=true

See PRIVACY.md for more information.

Quick reference

Option Type Default
schemaVersion number Required (1)
enabledWorkflows string[] ["simulator"]
experimentalWorkflowDiscovery boolean false
disableSessionDefaults boolean false
sessionDefaults object {}
incrementalBuildsEnabled boolean false
debug boolean false
debuggerBackend string "dap"
dapRequestTimeoutMs number 30000
dapLogEvents boolean false
launchJsonWaitMs number 8000
uiDebuggerGuardMode string "error"
axePath string Bundled
iosTemplatePath string GitHub default
iosTemplateVersion string Bundled version
macosTemplatePath string GitHub default
macosTemplateVersion string Bundled version

Environment variables (legacy)

Environment variables are supported for backwards compatibility but the config file is preferred.

Config option Environment variable
enabledWorkflows XCODEBUILDMCP_ENABLED_WORKFLOWS (comma-separated)
experimentalWorkflowDiscovery XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY
disableSessionDefaults XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS
incrementalBuildsEnabled INCREMENTAL_BUILDS_ENABLED
debug XCODEBUILDMCP_DEBUG
debuggerBackend XCODEBUILDMCP_DEBUGGER_BACKEND
dapRequestTimeoutMs XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS
dapLogEvents XCODEBUILDMCP_DAP_LOG_EVENTS
launchJsonWaitMs XBMCP_LAUNCH_JSON_WAIT_MS
uiDebuggerGuardMode XCODEBUILDMCP_UI_DEBUGGER_GUARD_MODE
axePath XCODEBUILDMCP_AXE_PATH
iosTemplatePath XCODEBUILDMCP_IOS_TEMPLATE_PATH
iosTemplateVersion XCODEBUILD_MCP_IOS_TEMPLATE_VERSION
macosTemplatePath XCODEBUILDMCP_MACOS_TEMPLATE_PATH
macosTemplateVersion XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION
(no config option) XCODEBUILDMCP_SENTRY_DISABLED

Config file takes precedence over environment variables when both are set.

Related docs