XcodeBuild MCP — Use Cases, Install & Live Demo

Why use it

Key features

Build and test any Xcode project or workspace (schemes, configurations, destinations)
Boot simulators, install apps, launch, send URLs, type text, tap coordinates
Capture screenshots and system/app logs per run
Swift Package Manager support alongside .xcodeproj
Discovers projects in a directory to minimize path-typing in prompts

Live Demo

What it looks like in practice

xcodebuild.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "xcodebuild",
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "xcodebuild": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "xcodebuildmcp@latest"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add xcodebuild -- npx -y xcodebuildmcp@latest

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use XcodeBuild

Verify AI-generated iOS code actually builds and runs on a simulator

👤 iOS devs using Claude for feature work, SwiftUI prototyping ⏱ ~15 min intermediate

When to use: Claude just wrote or edited SwiftUI views. Before saying 'done', you want to compile, run on simulator, and screenshot.

Prerequisites

Xcode installed — Xcode 15+ from the Mac App Store; confirm with xcodebuild -version
A bootable simulator — Xcode → Settings → Platforms → iOS Simulator downloaded

Flow

Discover the project and build

Find the Xcode project in /Users/me/Projects/MyApp. Build scheme 'MyApp' for iOS Simulator destination 'iPhone 16'. Report any errors or warnings.✓ Copied

→ Build succeeds, or specific errors with file:line
Boot simulator, install, launch

Boot an iPhone 16 simulator if not already booted. Install the built app and launch it. Take a screenshot after 3 seconds.✓ Copied

→ App running; screenshot captured
Drive the feature

Tap the 'Sign Up' button, type '[email protected]' in the email field, tap Submit. Screenshot after each step.✓ Copied

→ Sequence of screenshots showing the flow; or a clear tap-failed error

Outcome: Before/after screenshots that prove the feature works, committed alongside the code.

Pitfalls

Tapping by coordinate is fragile across device sizes — Prefer accessibility-label based taps when the MCP supports them; use coordinates only as fallback
Simulator build uses a different architecture than a real device — For architecture-sensitive code, also build for a physical device at least once before merging

Combine with: filesystem · github

Run your Xcode unit and UI tests from chat and triage failures

👤 iOS devs who want fast test feedback without switching to Xcode ⏱ ~10 min beginner

When to use: You've made a change, want to run ⌘U equivalent, and have Claude parse failures.

Flow

Run tests

Run all tests for scheme 'MyApp' on destination 'iPhone 16'. Show me any failures with file, line, and expectation.✓ Copied

→ Pass count plus failure list with locations
Focus on one failure

For the first failure, read the source file and tell me whether the test is wrong or the code is wrong. Be specific.✓ Copied

→ Clear diagnosis, not 'it could be either'
Fix and rerun

Apply the fix. Re-run only the failing test to confirm green.✓ Copied

→ Green rerun

Outcome: Tests back to green with a focused rerun, not a whole-suite rerun.

Pitfalls

xcodebuild test is slow on cold caches — Use -only-testing: flag to narrow; the MCP exposes this via test-by-identifier

Combine with: github

Diagnose a cryptic Xcode build error

👤 iOS devs who hit a 'linker error / missing framework / signing' wall ⏱ ~20 min intermediate

When to use: xcodebuild fails and the error output is 4000 lines of noise.

Flow

Build and capture the raw failure

Build scheme 'MyApp' and return only the lines containing 'error:' or 'warning:', plus 3 lines of context around each.✓ Copied

→ Focused error list without noise
Explain the first error

Explain the first error in human terms. What's Xcode actually complaining about, and what are the top 3 causes?✓ Copied

→ Plain-English diagnosis with likely causes
Apply fix and rebuild

Apply the most likely fix (check Info.plist/entitlements/Package.swift as needed), rebuild, and confirm the error is gone.✓ Copied

→ Clean build

Outcome: Unstuck from the build wall without a 2-hour Stack Overflow rabbit hole.

Pitfalls

Some errors are DerivedData staleness — When all else fails: clean DerivedData via the MCP's clean tool, then rebuild

Combine with: filesystem

Capture an app crash on simulator and find the root cause

👤 iOS devs hunting a reproducible crash ⏱ ~20 min advanced

When to use: Your app crashes on a specific flow in simulator, and you want Claude to read the crash log.

Flow

Reproduce with log capture

Launch MyApp on iPhone 16 simulator. Start log capture. Perform this flow: open Settings, tap 'Clear Cache'. Stop log capture when the app dies.✓ Copied

→ Crash reproduced, logs saved
Parse the crash

Find the crash in the captured logs. Symbolicate if needed. Tell me the failing thread, the top 5 stack frames, and the likely line in our code.✓ Copied

→ Symbolicated stack trace pointing at a specific source file
Propose the fix

Based on the stack trace and the surrounding code, what's the minimum change to fix it? Apply it.✓ Copied

→ Targeted fix, not a big refactor

Outcome: A fixed crash with symbolicated evidence you can paste into the PR.

Pitfalls

Release-config crashes don't symbolicate without dSYMs — Use Debug configuration for repro; separately test Release to confirm fix

Combine with: sentry · github

Combinations

Pair with other MCPs for X10 leverage

xcodebuild + filesystem

Edit Swift → build → screenshot → iterate, entirely in one chat

Edit ContentView.swift to add a dark-mode toggle. Build MyApp for iPhone 16, run it, take a screenshot in both light and dark mode.✓ Copied

xcodebuild + github

Fix an issue, verify on simulator, open PR with a screenshot

Issue #42 says the login button is misaligned in landscape. Reproduce on iPad simulator, fix the SwiftUI layout, attach before/after screenshots to the PR.✓ Copied

xcodebuild + sentry

Reproduce a Sentry-reported crash on simulator with identical conditions

Sentry crash iOS-113 happened on iOS 18.1 with user locale fr-FR. Boot a matching simulator, reproduce, and fix.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
discover_projects	directory: str	Find what to build in a repo without path-typing	free
build_project	project: str, scheme: str, destination: str, configuration?: 'Debug'\|'Release'	Build an .xcodeproj or .xcworkspace for a destination	free
build_spm_package	path: str	Build a Swift Package (no .xcodeproj)	free
test_project	project, scheme, destination, only_testing?: str[]	Run the test suite; use only_testing to narrow	free
list_simulators	none	See what simulators exist and which are booted	free
boot_simulator	simulator_id or name: str	Bring a simulator up before installing apps	free
install_app	simulator_id: str, app_path: str	Install the built .app on a booted simulator	free
launch_app	simulator_id: str, bundle_id: str	Start the installed app	free
tap_at / type_text / send_url	simulator params	Drive the UI	free
screenshot	simulator_id: str, path?: str	Capture visual state	free
start_log_capture / stop_log_capture	simulator_id	Capture console/system logs for a session	free
clean	project, scheme?	Blow away DerivedData for that project when builds go weird	free

Cost & Limits

What this costs to run

API quota: None — everything runs locally via xcodebuild/simctl
Tokens per call: Build logs can be huge. Prefer filtering to errors/warnings rather than full log dumps
Monetary: Free (requires a Mac with Xcode, which is its own cost)
Tip: Run incremental builds, not clean builds, by default. Only clean when DerivedData gets weird.

Security

Permissions, secrets, blast radius

Credential storage: No credentials at the MCP layer. Code signing credentials live in your Mac's Keychain as usual.

Data egress: None from the MCP. xcodebuild may fetch dependencies (SPM, CocoaPods) from their usual sources.

Never grant: don't let the agent alter codesign identities or provisioning profiles without confirmation

Simulator builds differ from device builds. Always test on a real device before release.
The MCP can execute Xcode build scripts (Run Script phases) which can do anything — treat any untrusted project as you would untrusted code.

Troubleshooting

Common errors and fixes

xcodebuild: command not found

Xcode Command Line Tools missing or not selected. Run xcode-select --install then sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.

Verify: xcodebuild -version

No such destination 'iPhone 16'

Simulator with that name isn't downloaded for the active Xcode. Open Xcode → Settings → Platforms → download iOS runtime. Or use list_simulators and pick an existing one.

Verify: xcrun simctl list devices

Build succeeds but app won't launch — 'NSException'

Check app logs via start_log_capture right before launching. Often Info.plist missing key, or entitlements mismatch.

Tests hang on a SwiftUI preview

SwiftUI previews can deadlock xcodebuild test in rare cases. Disable preview helpers in test schemes, or run with -disable-concurrent-testing.

Alternatives

XcodeBuild vs others

Alternative	When to use it instead	Tradeoff
Direct shell MCP running xcodebuild	You want max flexibility and accept the security tradeoff of a raw shell MCP	No ergonomics; Claude has to know every xcodebuild flag
JetBrains MCP (AppCode is EOL)	You're in JetBrains IDE — doesn't apply to iOS anymore	Not an iOS alternative today
Fastlane via shell	You need signed builds and TestFlight uploads, not just simulator verification	Much heavier; out of scope for inner-loop dev

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills