xcodebuildmcp_skill

Overview

This skill is the official XcodeBuildMCP interface for iOS, macOS, watchOS, tvOS, and visionOS development tasks. It centralizes build, test, run, debug, simulator/device management, logging, and UI automation commands into a consistent MCP workflow. Use it instead of calling raw xcodebuild/xcrun/simctl to simplify common development operations and avoid tool discovery friction.

How this skill works

Before running any workflow, the session defaults must be shown and set so tools operate with the correct project, scheme, destination, and device. The skill exposes focused tool groups — project discovery, simulator and device management, macOS builds, logging, debugging, UI automation, SwiftPM, scaffolding, cleaning, and diagnostics — and routes operations through MCP-managed commands. If a capability is missing, it guides you to discover or enable additional MCP workflows or tool schemas.

When to use it

• Building or running apps on simulators, devices, or macOS without calling xcodebuild directly.
• Launching automated test runs on simulators, devices, or macOS targets.
• Capturing device or simulator logs and recording simulator sessions for debugging or CI artifacts.
• Attaching LLDB, setting breakpoints, or inspecting stack frames and variables during a debug session.
• Driving UI automation: taps, swipes, screenshots, view-hierarchy snapshots, and simulator hardware controls.

Best practices

• Always call session_show_defaults, then session_set_defaults to populate project, scheme, and destination values before other actions.
• Use discover_projs and list_schemes to confirm the correct workspace/project and scheme when switching targets.
• Prefer build_run_* or build_* tools provided by the skill rather than composing raw xcodebuild invocations.
• Start log capture (start_sim_log_cap / start_device_log_cap) before running the app to ensure no logs are missed.
• Use snapshot_ui and screenshots to debug UI issues; record_sim_video for repros of complex interactions.

Example use cases

• Boot a simulator, build the app for sim, install it, and launch with live logs for a manual test session.
• Run a full test suite on an iOS simulator, capture logs, and record a failing test as a video for triage.
• Attach LLDB to a hung simulator app, add a breakpoint, inspect variables, and continue execution.
• Build and run a macOS app from the workspace, then capture its logs and take a screenshot of the window.
• Scaffold a minimal iOS project, run swift package tests, and clean build artifacts as part of CI setup.