Skip to content

CONFIGURATION.md

Latest commit

 

History

History
77 lines (55 loc) · 3.82 KB

CONFIGURATION.md

File metadata and controls

77 lines (55 loc) · 3.82 KB

Configuration

XcodeBuildMCP is configured through environment variables provided by your MCP client. Here is a single example showing how to add options to a typical MCP config:

"XcodeBuildMCP": {
  "command": "npx",
  "args": ["-y", "xcodebuildmcp@latest"],
  "env": {
    "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery",
    "INCREMENTAL_BUILDS_ENABLED": "false",
    "XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS": "false",
    "XCODEBUILDMCP_SENTRY_DISABLED": "false"
  }
}

Workflow selection

By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool surface for a specific workflow, set XCODEBUILDMCP_ENABLED_WORKFLOWS to a comma-separated list of workflow directory names. The session-management workflow is always auto-included since other tools depend on it. When XCODEBUILDMCP_DEBUG=true, the doctor workflow is also auto-included.

Available workflows:

  • device (14 tools) - iOS Device Development
  • simulator (19 tools) - iOS Simulator Development
  • logging (4 tools) - Log Capture & Management
  • macos (11 tools) - macOS Development
  • project-discovery (5 tools) - Project Discovery
  • project-scaffolding (2 tools) - Project Scaffolding
  • utilities (1 tool) - Project Utilities
  • session-management (3 tools) - session-management
  • workflow-discovery (1 tool) - Workflow Discovery
  • debugging (8 tools) - Simulator Debugging
  • simulator-management (8 tools) - Simulator Management
  • swift-package (6 tools) - Swift Package Manager
  • doctor (1 tool) - System Doctor
  • ui-testing (11 tools) - UI Testing & Automation

Incremental build support

XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the INCREMENTAL_BUILDS_ENABLED environment variable to true.

Important

Incremental builds are highly experimental and your mileage may vary. Please report issues to the issue tracker.

Experimental workflow discovery

Set XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true to auto-include the workflow-discovery workflow at startup.

The workflow discovery tool lets agents and clients enable or disable workflows at runtime. This can reduce upfront context by loading only what is needed as the session evolves. Note: most clients do not yet support the MCP notifications required for an agent harness to re-query the tool list after changes.

Session-aware opt-out

By default, XcodeBuildMCP uses a session-aware mode: the LLM (or client) sets shared defaults once (simulator, device, project/workspace, scheme, etc.), and all tools reuse them. This cuts context bloat not just in each call payload, but also in the tool schemas themselves.

If you prefer the older, explicit style where each tool requires its own parameters, set XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true. This restores the legacy schemas with per-call parameters while still honoring any session defaults you choose to set.

Leave this unset for the streamlined session-aware experience; enable it to force explicit parameters on each tool call.

Sentry telemetry opt-out

If you do not wish to send error logs to Sentry, set XCODEBUILDMCP_SENTRY_DISABLED=true.

AXe binary override

UI automation and simulator video capture require the AXe binary. By default, XcodeBuildMCP uses the bundled AXe when available, then falls back to PATH. To force a specific binary location, set XCODEBUILDMCP_AXE_PATH (preferred). AXE_PATH is also recognized for compatibility.

Example:

XCODEBUILDMCP_AXE_PATH=/opt/axe/bin/axe

Related docs