Docs/Reference/Configuration/Environment Variables

Environment Variables

Every env var XcodeBuildMCP reads on startup. Use these to bootstrap MCP clients that can't supply workspace context directly.

Set env vars in the env field of your MCP client config (for example mcp_config.json for Windsurf, .vscode/mcp.json for VS Code, or claude_desktop_config.json for Claude Desktop). For repo-scoped structured settings, prefer .xcodebuildmcp/config.yaml, see Configuration.

Precedence#

session_set_defaults > .xcodebuildmcp/config.yaml > env vars. Each layer serves a different context:

Config file is the canonical home for structured, repo-scoped, version-controlled settings.
Env vars are best for flat startup defaults in MCP clients with limited workspace support.
Tool calls are for agent-driven runtime adjustments.

General settings#

Config option	Environment variable
`enabledWorkflows`	`XCODEBUILDMCP_ENABLED_WORKFLOWS` (comma-separated)
`experimentalWorkflowDiscovery`	`XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY`
Startup working directory	`XCODEBUILDMCP_CWD`
`disableSessionDefaults`	`XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS`
`disableXcodeAutoSync`	`XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC`
`incrementalBuildsEnabled`	`INCREMENTAL_BUILDS_ENABLED`
`filePathRenderStyle`	`XCODEBUILDMCP_FILE_PATH_RENDER_STYLE` (`list` or `tree`)
`debug`	`XCODEBUILDMCP_DEBUG`
`showTestTiming`	`XCODEBUILDMCP_SHOW_TEST_TIMING`
`sentryDisabled`	`XCODEBUILDMCP_SENTRY_DISABLED`
`debuggerBackend`	`XCODEBUILDMCP_DEBUGGER_BACKEND`
`dapRequestTimeoutMs`	`XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS`
`dapLogEvents`	`XCODEBUILDMCP_DAP_LOG_EVENTS`
`launchJsonWaitMs`	`XBMCP_LAUNCH_JSON_WAIT_MS`
MCP idle timeout	`XCODEBUILDMCP_MCP_IDLE_TIMEOUT_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`

Session default bootstrap#

Session default	Environment variable
`workspacePath`	`XCODEBUILDMCP_WORKSPACE_PATH`
`projectPath`	`XCODEBUILDMCP_PROJECT_PATH`
`scheme`	`XCODEBUILDMCP_SCHEME`
`configuration`	`XCODEBUILDMCP_CONFIGURATION`
`simulatorName`	`XCODEBUILDMCP_SIMULATOR_NAME`
`simulatorId`	`XCODEBUILDMCP_SIMULATOR_ID`
`simulatorPlatform`	`XCODEBUILDMCP_SIMULATOR_PLATFORM`
`deviceId`	`XCODEBUILDMCP_DEVICE_ID`
`platform`	`XCODEBUILDMCP_PLATFORM`
`useLatestOS`	`XCODEBUILDMCP_USE_LATEST_OS`
`arch`	`XCODEBUILDMCP_ARCH`
`suppressWarnings`	`XCODEBUILDMCP_SUPPRESS_WARNINGS`
`derivedDataPath`	`XCODEBUILDMCP_DERIVED_DATA_PATH`
`preferXcodebuild`	`XCODEBUILDMCP_PREFER_XCODEBUILD`
`bundleId`	`XCODEBUILDMCP_BUNDLE_ID`

MCP idle shutdown#

XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS is disabled by default (0). Set it to a positive number of milliseconds when you want an unused MCP server process to shut down gracefully after that idle period.

The server only exits when the timeout has elapsed, no MCP request is in flight, and no registered runtime operation is active.

Working directory override#

XCODEBUILDMCP_CWD overrides the directory XcodeBuildMCP uses to discover .xcodebuildmcp/config.yaml and resolve relative paths. Set this when the host that launches XcodeBuildMCP can configure environment variables but not the spawn directory (the most common case is MCP Inspector).

Variable	Behavior
`XCODEBUILDMCP_CWD`	Absolute path; supports a leading `~/`. Falls back to the original cwd with a warning if the directory cannot be entered.

Example: launch XcodeBuildMCP from anywhere and have it read ~/Projects/MyApp/.xcodebuildmcp/config.yaml:

json

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
      "env": {
        "XCODEBUILDMCP_CWD": "~/Projects/MyApp"
      }
    }
  }
}

If you have not set XCODEBUILDMCP_CWD, the working directory is whatever the host process spawned XcodeBuildMCP in.

Example#