XC-MCP: XCode CLI wrapper

Overview Schema Source Related Servers Discussions Admin

Build Xcode Scheme

xcodebuild-build

Build Xcode projects with smart defaults, tracking performance and offering concise summaries with on-demand full logs for efficient, error-aware compilation.

Instructions

xcodebuild-build

⚡ Build Xcode projects with intelligent defaults and performance tracking

What it does

Builds Xcode projects and workspaces with advanced learning capabilities that remember successful configurations and suggest optimal simulators per project. Uses progressive disclosure to provide concise summaries by default, with full build logs available on demand. Tracks build performance metrics (duration, errors, warnings) and learns from successful builds to improve future build suggestions.

Why you'd use it

Automatic smart defaults: remembers which simulator and config worked last time
Progressive disclosure: concise summaries prevent token overflow, full logs on demand
Performance tracking: measures build times and provides optimization insights
Structured errors: clear error messages instead of raw CLI stderr

Parameters

Required

projectPath (string): Path to .xcodeproj or .xcworkspace file
scheme (string): Build scheme name (use xcodebuild-list to discover)

Optional

configuration (string, default: 'Debug'): Build configuration (Debug/Release, defaults to cached or "Debug")
destination (string): Build destination (e.g., "platform=iOS Simulator,id=")
sdk (string): SDK to build against (e.g., "iphonesimulator", "iphoneos")
derivedDataPath (string): Custom derived data path for build artifacts

Returns

Structured JSON response with buildId (for progressive disclosure), success status, build summary (errors, warnings, duration), and intelligence metadata showing which smart defaults were applied. Use xcodebuild-get-details with buildId to retrieve full logs.

Examples

Minimal build with smart defaults

const result = await xcodebuildBuildTool({
  projectPath: "/path/to/MyApp.xcodeproj",
  scheme: "MyApp"
});

Explicit configuration

const release = await xcodebuildBuildTool({
  projectPath: "/path/to/MyApp.xcworkspace",
  scheme: "MyApp",
  configuration: "Release",
  destination: "platform=iOS Simulator,id=ABC-123"
});

xcodebuild-test: Run tests after building
xcodebuild-clean: Clean build artifacts
xcodebuild-get-details: Get full build logs (use with buildId)

Input Schema

TableJSON Schema

Name	Required	Default
`sdk`	No
`scheme`	Yes
`destination`	No
`projectPath`	Yes
`configuration`	No	Debug
`derivedDataPath`	No

Output Schema

TableJSON Schema

Name	Required	Description
`scheme`	Yes
`buildId`	Yes	Cache id for full build log (xcodebuild-get-details)
`success`	Yes
`durationMs`	Yes
`errorCount`	Yes
`warningCount`	Yes
`configuration`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv4.1.0Sep 14, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "buildId": {
+      "description": "Cache id for full build log (xcodebuild-get-details)",
+      "type": "string"
+    },
+    "configuration": {
+      "type": "string"
+    },
+    "durationMs": {
+      "type": "number"
+    },
+    "errorCount": {
+      "type": "number"
+    },
+    "scheme": {
+      "type": "string"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "warningCount": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "buildId",
+    "success",
+    "errorCount",
+    "warningCount",
+    "durationMs",
+    "scheme",
+    "configuration"
+  ],
+  "type": "object"
+}

Changed7 schema fields changedv1.1.0May 1, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

removedInput schema / properties / configuration / description

Removed value: -"Build configuration (Debug, Release, etc.)"

removedInput schema / properties / derivedDataPath / description
```
Removed value: -"Custom derived data path"
```

removedInput schema / properties / destination / description

Removed value: -"Build destination. If not provided, uses intelligent defaults based on project history and available simulators."

removedInput schema / properties / projectPath / description

Removed value: -"Path to .xcodeproj or .xcworkspace file"

removedInput schema / properties / scheme / description
```
Removed value: -"Build scheme name"
```

removedInput schema / properties / sdk / description

Removed value: -"SDK to use for building (e.g., \"iphonesimulator\", \"iphoneos\")"

First observedv1.0.0Aug 18, 2025

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the sparse annotations by disclosing that builds are non-readonly, use progressive disclosure, return a buildId, track performance metrics, and learn from successful builds. It also explains structured error handling. No contradiction with annotations is present, and this behavioral context substantially aids an agent in invoking the tool correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections: what it does, why use it, parameters, returns, examples, and related tools. It is somewhat verbose with marketing-style phrases like 'advanced learning capabilities' and 'optimization insights', but each section serves a functional purpose and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the minimal schema, the description covers all essential context: required vs optional parameters, smart-default behavior, return structure, buildId usage for logs, and related sibling tools. Despite an output schema existing, the description also explains the return shape, making it complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates by documenting all six parameters, marking required ones, providing defaults, giving example destination syntax, and explaining how to discover scheme names. This adds meaningful semantic value beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Builds Xcode projects and workspaces'. It clearly distinguishes this tool from siblings by naming related tools like xcodebuild-test, xcodebuild-clean, and xcodebuild-get-details. An agent can immediately understand what the tool does without inferring from the title alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use, including smart defaults, progressive disclosure, performance tracking, and structured errors. It references xcodebuild-list for discovering schemes and xcodebuild-get-details for retrieving full logs. It does not explicitly state when not to use this tool versus alternatives, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server