XC-MCP Xcode MCP Server

# xcodebuild-version ⚡ **Get Xcode and SDK version information** with structured output ## What it does Retrieves comprehensive version information about your Xcode installation and available SDKs. Returns structured JSON data that's easy to parse and validate, eliminating the need to parse raw command-line output. Validates Xcode installation before execution to provide clear error messages if Xcode is not properly configured. ## Why you'd use it - Validate environment before running builds or tests (CI/CD validation) - Check SDK availability for specific platform versions - Ensure consistent Xcode versions across team or build environments - Get structured version data for automated tooling and scripts ## Parameters ### Optional - **sdk** (string): Query specific SDK version (e.g., "iphoneos", "iphonesimulator") - **outputFormat** (string, default: 'json'): "json" or "text" output format ## Returns Structured JSON response containing Xcode version, build number, and SDK information. Falls back gracefully to text format for older Xcode versions that don't support JSON output. ## Examples ### Get Xcode version as JSON ```typescript const result = await xcodebuildVersionTool({ outputFormat: "json" }); ``` ### Query specific SDK ```typescript const sdkInfo = await xcodebuildVersionTool({ sdk: "iphoneos" }); ``` ## Related Tools - xcodebuild-showsdks: Show all available SDKs - xcodebuild-list: List project information

# xcodebuild-list ⚡ **List project targets, schemes, and configurations** with intelligent caching ## What it does Discovers and returns all available build targets, schemes, and configurations for an Xcode project or workspace. Uses 1-hour intelligent caching to remember results and avoid expensive re-runs of project discovery. Validates both Xcode installation and project path before execution to provide clear error messages if something is misconfigured. ## Why you'd use it - Discover available schemes before building or testing (essential for automation) - Validate project structure and configuration - Get structured project metadata for CI/CD pipelines - Avoid expensive repeated queries with 1-hour caching ## Parameters ### Required - **projectPath** (string): Path to .xcodeproj or .xcworkspace file ### Optional - **outputFormat** (string, default: 'json'): "json" or "text" output format ## Returns Structured JSON containing all targets, schemes, configurations, and project information. Consistent format across .xcodeproj and .xcworkspace project types. Results are cached for 1 hour to speed up subsequent queries. ## Examples ### List schemes for a project ```typescript const info = await xcodebuildListTool({ projectPath: "/path/to/MyApp.xcodeproj" }); ``` ### List with text output ```typescript const textInfo = await xcodebuildListTool({ projectPath: "/path/to/MyApp.xcworkspace", outputFormat: "text" }); ``` ## Related Tools - xcodebuild-build: Build discovered schemes - xcodebuild-test: Test discovered schemes

# 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=<UDID>") - **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 ```typescript const result = await xcodebuildBuildTool({ projectPath: "/path/to/MyApp.xcodeproj", scheme: "MyApp" }); ``` ### Explicit configuration ```typescript const release = await xcodebuildBuildTool({ projectPath: "/path/to/MyApp.xcworkspace", scheme: "MyApp", configuration: "Release", destination: "platform=iOS Simulator,id=ABC-123" }); ``` ## Related Tools - xcodebuild-test: Run tests after building - xcodebuild-clean: Clean build artifacts - xcodebuild-get-details: Get full build logs (use with buildId)

# xcodebuild-clean ⚡ **Clean build artifacts** with validation and structured output ## What it does Removes build artifacts and intermediate files for an Xcode project or workspace. Pre-validates that the project exists and Xcode is properly installed before executing, providing clear error messages if something is misconfigured. Returns structured JSON responses with execution status, duration, and any errors encountered during the clean operation. ## Why you'd use it - Resolve build issues by removing stale or corrupted build artifacts - Free up disk space occupied by intermediate build files - Ensure clean builds from scratch without cached compilation results - Get structured feedback with execution time and success status ## Parameters ### Required - **projectPath** (string): Path to .xcodeproj or .xcworkspace file - **scheme** (string): Build scheme name to clean ### Optional - **configuration** (string): Build configuration to clean (e.g., "Debug", "Release") ## Returns Structured JSON response containing success status, command executed, execution duration, output messages, and exit code. Includes both stdout and stderr for comprehensive debugging. Operation typically completes in under 3 minutes. ## Examples ### Clean default configuration ```typescript const result = await xcodebuildCleanTool({ projectPath: "/path/to/MyApp.xcodeproj", scheme: "MyApp" }); ``` ### Clean specific configuration ```typescript const cleanRelease = await xcodebuildCleanTool({ projectPath: "/path/to/MyApp.xcworkspace", scheme: "MyApp", configuration: "Release" }); ``` ## Related Tools - xcodebuild-build: Build after cleaning - xcodebuild-list: Discover available schemes

# xcodebuild-test ⚡ **Run Xcode tests** with intelligent defaults and progressive disclosure ## What it does Executes unit and UI tests for Xcode projects with advanced learning that remembers successful test configurations and suggests optimal simulators per project. Provides detailed test metrics (passed/failed/skipped) with progressive disclosure to prevent token overflow. Supports test filtering (-only-testing, -skip-testing), test plans, and test-without-building mode for faster iteration. Learns from successful test runs to improve future suggestions. ## Why you'd use it - Automatic smart defaults: remembers which simulator and config worked for tests - Detailed test metrics: structured pass/fail/skip counts instead of raw output - Progressive disclosure: concise summaries with full logs available via testId - Test filtering: run specific tests or skip problematic ones with -only-testing/-skip-testing ## Parameters ### Required - **projectPath** (string): Path to .xcodeproj or .xcworkspace file - **scheme** (string): Test scheme name (use xcodebuild-list to discover) ### Optional - **configuration** (string, default: 'Debug'): Build configuration (Debug/Release, defaults to cached or "Debug") - **destination** (string): Test destination (e.g., "platform=iOS Simulator,id=<UDID>") - **sdk** (string): SDK to test against (e.g., "iphonesimulator") - **derivedDataPath** (string): Custom derived data path - **testPlan** (string): Test plan name to execute - **onlyTesting** (string[]): Array of test identifiers to run exclusively - **skipTesting** (string[]): Array of test identifiers to skip - **testWithoutBuilding** (boolean): Run tests without building (requires prior build) ## Returns Structured JSON with testId (for progressive disclosure), success status, test summary (total/passed/failed/skipped counts), failure details (first 3 failures), and cache metadata showing which smart defaults were applied. Use xcodebuild-get-details with testId for full logs. ## Examples ### Run all tests with smart defaults ```typescript const result = await xcodebuildTestTool({ projectPath: "/path/to/MyApp.xcodeproj", scheme: "MyApp" }); ``` ### Run specific tests only ```typescript const filtered = await xcodebuildTestTool({ projectPath: "/path/to/MyApp.xcworkspace", scheme: "MyApp", onlyTesting: ["MyAppTests/testLogin", "MyAppTests/testLogout"] }); ``` ### Fast iteration with test-without-building ```typescript const quick = await xcodebuildTestTool({ projectPath: "/path/to/MyApp.xcodeproj", scheme: "MyApp", testWithoutBuilding: true }); ``` ## Complete JSON Examples ### Run All Tests ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp"} ``` ### Run Specific Test Plan ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "testPlan": "IntegrationTests"} ``` ### Run Only Specific Tests ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "onlyTesting": ["MyAppTests/LoginTests", "MyAppTests/AuthTests/testLogin"]} ``` ### Skip Specific Tests ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "skipTesting": ["MyAppTests/SlowTests", "MyAppUITests"]} ``` ### Test Without Building (Using Previous Build) ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "testWithoutBuilding": true} ``` ### Test with Specific Destination ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "destination": "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.0"} ``` ### Release Configuration Testing ```json {"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "configuration": "Release"} ``` ## Related Tools - xcodebuild-build: Build before testing - xcodebuild-get-details: Get full test logs (use with testId) - simctl-list: See available test simulators

Complete iOS debug workflow: build → install → test cycle with validation to prevent testing stale app versions