justbecauselabs XcodeBuildMCP CLI
This skill is for AI agents. It positions the XcodeBuildMCP CLI as a low‑overhead alternative to MCP tool calls: agents can already run shell commands, and the CLI exposes the same tool surface without the schema‑exchange cost. Prefer the CLI over raw xcodebuild, xcrun, or simctl.
When To Use This CLI (Capabilities And Workflows)
- When you need build/test/run/debugging/logging/UI automation capabilities.
- When you want simulator/device management capabilities.
- When you want AI optimized tools and tool responses.
- When you need project discovery capabilities (schemes, bundle IDs, app paths).
Command Discovery
Use --help to discover workflows, tools, and arguments.
xcodebuildmcp --help
xcodebuildmcp tools --help
xcodebuildmcp tools --json
xcodebuildmcp <workflow> --help
xcodebuildmcp <workflow> <tool> --help
Notes:
- Use
--json '{...}'for complex arguments and--output jsonif you need machine-readable results (not recommended).
Common Workflows
Build And Run On Simulator
- List simulators and pick a device name or UDID.
- Build and run.
If app and project details are not known:
xcodebuildmcp simulator discover-projs --workspace-root .
xcodebuildmcp simulator list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp simulator list-sims
To build, install and launch the app in one command:
xcodebuildmcp simulator build-run-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
Build only
When you only need to check that there are no build errors, you can build without running the app.
xcodebuildmcp simulator build-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
Run Tests
When you need to run tests, you can do so with the test-sim tool.
xcodebuildmcp simulator test-sim --scheme MyAppTests --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
Install And Launch On Physical Device
xcodebuildmcp device list-devices
xcodebuildmcp device build-device --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-device-app-path --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-app-bundle-id --app-path /path/to/MyApp.app
xcodebuildmcp device install-app-device --device-id DEVICE_UDID --app-path /path/to/MyApp.app
xcodebuildmcp device launch-app-device --device-id DEVICE_UDID --bundle-id com.example.MyApp --app-path /path/to/MyApp.app
Capture Logs On Simulator
xcodebuildmcp logging start-sim-log-cap --simulator-id SIMULATOR_UDID --bundle-id com.example.MyApp
xcodebuildmcp logging stop-sim-log-cap --log-session-id LOG_SESSION_ID
Debug A Running App (Simulator)
- Launch the app.
- Attach the debugger after the app is fully launched.
Launch if not already running:
xcodebuildmcp simulator launch-app-sim --bundle-id com.example.MyApp --simulator-id SIMULATOR_UDID
Attach the debugger:
It's generally a good idea to wait for 1-2s for the app to fully launch before attaching the debugger.
xcodebuildmcp debugging debug-attach-sim --bundle-id com.example.MyApp --simulator-id SIMULATOR_UDID
To add/remove breakpoints, inspect stack/variables, and issue arbitrary LLDB commands, view debugging help:
xcodebuildmcp debugging --help
Inspect UI And Automate Input
Snapshot UI accessibility tree, tap/swipe/type, and capture screenshots:
xcodebuildmcp ui-automation snapshot-ui --simulator-id SIMULATOR_UDID
xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --x 200 --y 400
xcodebuildmcp ui-automation type-text --simulator-id SIMULATOR_UDID --text "hello"
xcodebuildmcp ui-automation screenshot --simulator-id SIMULATOR_UDID --return-format path
To see all UI automation tools, view UI automation help:
xcodebuildmcp ui-automation --help
macOS App Build/Run
xcodebuildmcp macos build-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
xcodebuildmcp macos build-run-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
To see all macOS tools, view macOS help:
xcodebuildmcp macos --help
SwiftPM Package Workflows
xcodebuildmcp swift-package list --package-path ./MyPackage
xcodebuildmcp swift-package build --package-path ./MyPackage
xcodebuildmcp swift-package test --package-path ./MyPackage
To see all SwiftPM tools, view SwiftPM help:
xcodebuildmcp swift-package --help
Project Discovery
xcodebuildmcp project-discovery discover-projs --workspace-root .
xcodebuildmcp project-discovery list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp project-discovery get-app-bundle-id --app-path ./Build/MyApp.app
To see all project discovery tools, view project discovery help:
xcodebuildmcp project-discovery --help
Scaffolding new projects
It's worth viewing the --help for the scaffolding tools to see the available options. Here are some minimal examples:
xcodebuildmcp project-scaffolding scaffold-ios-project --project-name MyApp --output-path ./Projects
xcodebuildmcp project-scaffolding scaffold-macos-project --project-name MyMacApp --output-path ./Projects
To see all project scaffolding tools, view project scaffolding help:
xcodebuildmcp project-scaffolding --help
Daemon Notes (Stateful Tools)
Stateful tools (logs, debug, video recording, background run) go through a per-workspace daemon that auto-starts, if you find you are getting errors with the stateful tools, you can manage the daemon process manually.
xcodebuildmcp daemon status
xcodebuildmcp daemon restart
To see all daemon commands, view daemon help:
xcodebuildmcp daemon --help