xcodebuild-mcp

A Model Context Protocol (MCP) server that exposes xcodebuild and xcrun simctl operations as tools for AI assistants like Claude. This enables AI-powered iOS/macOS development workflows by providing direct access to Xcode build, test, and simulator management capabilities.

Features

• Project Discovery - Query Xcode version, schemes, targets, configurations, build settings, and available SDKs
• Build Operations - Build, clean, and archive Xcode projects and workspaces
• Test Execution - Run tests with filtering, enumerate available tests, and get detailed failure reports
• Simulator Management - List, boot, shutdown simulators and install/launch/uninstall apps
• Intelligent Output Parsing - Automatic extraction of errors, warnings, and test failures from xcodebuild output
• Timeout Handling - Configurable timeouts for long-running build and test operations

Prerequisites

• macOS 14.0 or later
• Xcode Command Line Tools installed (xcode-select --install)

Installation

Via Homebrew (Recommended)

brew tap redne-w/xcodebuild-mcp
brew install xcodebuild-mcp

Building from Source

1. Clone the repository:

   git clone https://github.com/redne-w/xcodebuild-mcp.git
   cd xcodebuild-mcp
   

2. Build the release binary:

   swift build -c release
   

3. The binary will be available at .build/release/xcodebuild-mcp

Configuring with Claude Code

Add the server to your Claude Code settings file (~/.claude/settings.json or project-level .claude/settings.local.json):

{
  "mcpServers": {
    "xcodebuild": {
      "type": "stdio",
      "command": "xcodebuild-mcp"
    }
  }
}

If installed via Homebrew, xcodebuild-mcp will be in your PATH. If built from source, use the full path to the binary.

Restart Claude Code and verify the server is running with the /mcp command.

Available Tools

Discovery Tools

| Tool | Description | Required Parameters | |------|-------------|---------------------| | xcode_version | Get installed Xcode version and build number | None | | list_schemes | List available schemes in project/workspace | None (optional: project_path, workspace_path) | | list_targets | List targets in the project | None (optional: project_path) | | list_configurations | List build configurations | None (optional: project_path, workspace_path) | | show_destinations | Show valid build destinations for a scheme | scheme | | show_build_settings | Get build settings for scheme/target | None (optional: scheme, target, configuration, project_path, workspace_path) | | show_sdks | List installed SDKs | None |

Build Tools

| Tool | Description | Required Parameters | |------|-------------|---------------------| | build | Build a project or workspace scheme | scheme | | clean | Clean build artifacts for a scheme | scheme | | archive | Create an archive for distribution | scheme, archive_path |

Test Tools

| Tool | Description | Required Parameters | |------|-------------|---------------------| | test | Run tests for a scheme | scheme | | enumerate_tests | List available tests without running them | scheme |

Simulator Tools

| Tool | Description | Required Parameters | |------|-------------|---------------------| | list_simulators | List available iOS simulators | None (optional: filter, search_term) | | boot_simulator | Start a simulator | device_id | | shutdown_simulator | Stop a simulator | device_id | | install_app | Install an app on a simulator | device_id, app_path | | launch_app | Launch an app on a simulator | device_id, bundle_id | | uninstall_app | Uninstall an app from a simulator | device_id, bundle_id |

Usage Examples

Get Xcode Version

mcp__xcodebuild__xcode_version

Returns the installed Xcode version and build number.

List Available Schemes

mcp__xcodebuild__list_schemes with project_path="/path/to/MyApp.xcodeproj"

Or for a workspace:

mcp__xcodebuild__list_schemes with workspace_path="/path/to/MyApp.xcworkspace"

Build a Scheme

mcp__xcodebuild__build with scheme="MyApp" destination="platform=iOS Simulator,name=iPhone 15"

Additional options:

• configuration: Build configuration (e.g., "Debug", "Release")
• project_path or workspace_path: Path to project/workspace
• derived_data_path: Custom derived data location
• extra_args: Additional xcodebuild arguments

Run Tests

mcp__xcodebuild__test with scheme="MyAppTests" destination="platform=iOS Simulator,name=iPhone 15"

Additional options:

• test_plan: Specific test plan to use
• only_testing: Array of test identifiers to run (e.g., ["MyTests/testExample"])
• skip_testing: Array of test identifiers to skip
• parallel_testing: Enable/disable parallel testing
• result_bundle_path: Path to save test results

Enumerate Tests

mcp__xcodebuild__enumerate_tests with scheme="MyAppTests" destination="platform=iOS Simulator,name=iPhone 15"

Lists all available tests without running them.

List Simulators

mcp__xcodebuild__list_simulators with filter="available"

Filter options:

• all: Show all simulators
• available: Show only available simulators (default)
• booted: Show only running simulators

You can also search by name:

mcp__xcodebuild__list_simulators with search_term="iPhone 15"

Boot and Use a Simulator

mcp__xcodebuild__boot_simulator with device_id="iPhone 15 Pro"

Or by UDID:

mcp__xcodebuild__boot_simulator with device_id="12345678-ABCD-1234-ABCD-1234567890AB"

Install and Launch an App

mcp__xcodebuild__install_app with device_id="booted" app_path="/path/to/MyApp.app"
mcp__xcodebuild__launch_app with device_id="booted" bundle_id="com.example.MyApp"

Create an Archive

mcp__xcodebuild__archive with scheme="MyApp" archive_path="/path/to/MyApp.xcarchive" configuration="Release"

Configuration Options

Build Tool Options

| Parameter | Description | |-----------|-------------| | scheme | The scheme to build (required) | | destination | Build destination (e.g., platform=iOS Simulator,name=iPhone 15) | | configuration | Build configuration (Debug, Release) | | project_path | Path to .xcodeproj file | | workspace_path | Path to .xcworkspace file | | derived_data_path | Custom derived data path | | extra_args | Additional xcodebuild arguments as array |

Test Tool Options

| Parameter | Description | |-----------|-------------| | scheme | The scheme to test (required) | | destination | Test destination | | test_plan | Test plan name | | only_testing | Array of test identifiers to include | | skip_testing | Array of test identifiers to exclude | | configuration | Build configuration for tests | | result_bundle_path | Path to save result bundle | | parallel_testing | Enable parallel testing (boolean) |

Simulator Tool Options

| Parameter | Description | |-----------|-------------| | device_id | Simulator UDID, name, or "booted" | | filter | Filter simulators: "all", "available", "booted" | | search_term | Search simulators by name | | app_path | Path to .app bundle | | bundle_id | App bundle identifier | | args | Launch arguments array | | wait_for_debugger | Wait for debugger before launch |

Timeouts

The server uses configurable timeouts for different operations:

• Default timeout: 2 minutes (120 seconds) - Used for discovery and simulator operations
• Build timeout: 10 minutes (600 seconds) - Used for build, test, and archive operations

Troubleshooting

Server not appearing in Claude Code

1. Verify the binary path in your settings is correct
2. Ensure the binary has execute permissions: chmod +x .build/release/xcodebuild-mcp
3. Restart Claude Code completely

Build/Test timeouts

For large projects, builds may exceed the 10-minute timeout. You can modify ProcessRunner.buildTimeout in the source and rebuild.

Simulator operations failing

1. Ensure Xcode Command Line Tools are installed: xcode-select --install
2. Verify simulators are available: xcrun simctl list devices
3. Some operations require a booted simulator - use boot_simulator first

Permission errors

The MCP server needs permission to run xcodebuild and xcrun. On first run, macOS may prompt for permission.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.