get_coverage_report
Show per-target code coverage from an xcresult bundle.
LABSCO SUMMARY
The agent stops shelling out to xcodebuild.
Stable tool names, pre-parsed build diagnostics and session defaults are what make an iOS loop survivable for an agent: it stops re-supplying the scheme on every call and stops parsing raw build output.
What it is
An MCP server and CLI from Sentry, shipped as one binary. By the project site's count it exposes 82 tools across 15 workflows for iOS, iPadOS, macOS, watchOS, tvOS and visionOS, and every tool is callable from the terminal for scripting and CI. Both modes share the same code, the same config file and the same per-workspace daemon.
What you get
- Project discovery for
.xcodeproj,.xcworkspaceand Swift packages, then structured build, test and clean for simulators, devices and macOS targets - Build and run in one call — compile, install, launch and stream logs — instead of a multi-step sequence the agent can get wrong
- Simulator lifecycle: boot, install, launch, capture logs, record video and reset state
- Physical devices over USB or Wi-Fi, including paired iPhones, iPads, Apple Watches and Vision Pros
- LLDB: attach, set breakpoints, inspect frames and variables, and run raw commands
- UI automation: tap, swipe, type, gesture, and inspect semantic element refs read off the view hierarchy
- Swift Package Manager builds, tests and runs, executables included, with long-running processes handled by the daemon
- Code coverage as per-target summaries and function-level uncovered-line reports from xcresult
- Session defaults so workspace, scheme and simulator are set once instead of resupplied on every call
- Two optional agent skills installed by
xcodebuildmcp init— one that primes an agent on the MCP tools, one on the CLI
Requirements
macOS 14.5 or later and Xcode 16.x or later. Install with brew install getsentry/xcodebuildmcp/xcodebuildmcp, or npm install -g xcodebuildmcp@latest on Node.js 18 or newer — Homebrew does not need Node at all. Most clients can also run it on demand with npx -y xcodebuildmcp@latest mcp. Loading every workflow is a lot of context, so XCODEBUILDMCP_ENABLED_WORKFLOWS narrows startup to the workflows you actually use. Device tools need code signing configured in Xcode first. Sentry reporting covers the tool's own runtime errors only — build, test and config failures in your project are never sent and tool arguments and outputs are never captured — and XCODEBUILDMCP_SENTRY_DISABLED=true switches it off.
Setup effort
One command — npm install -g xcodebuildmcp@latest
USE CASES
01
Letting an agent fix its own build errors
Build returns parsed diagnostics rather than a wall of xcodebuild output, so the agent reads the error, edits, and builds again without a human translating in between.
02
Verifying a change actually works on screen
One call compiles, installs, launches and streams the logs, then the UI automation tools tap and type through the flow. What you get back is whether the change works, not whether it compiled.
03
Chasing a crash with the debugger
Attach LLDB, set the breakpoint, inspect the frames and variables, and drop to raw LLDB when the structured tools run out. The debugging session happens where the agent already is.
04
Testing on the phone in your hand
Install and launch on a paired iPhone, iPad, Watch or Vision Pro over USB or Wi-Fi, with logs coming back. Set code signing up in Xcode first — the device tools depend on it.
05
Running the same steps in CI
Every tool is a CLI command as well, so the sequence an agent worked out interactively becomes a script. Same binary, same config, same daemon.
06
Keeping the tool list from eating the context window
Set XCODEBUILDMCP_ENABLED_WORKFLOWS to the workflows you actually use — simulator and project discovery, say — and the other tools never load. Worth doing on a project that only ever targets one platform.
82 tools
Listed in project docs. Your client may show a different list.
get_file_coverage
Show function-level coverage and uncovered line ranges for a specific file.
debug_attach_sim
Attach LLDB to sim app.
debug_breakpoint_add
Add breakpoint.
debug_breakpoint_remove
Remove breakpoint.
debug_continue
Continue debug session.
debug_detach
Detach debugger.
debug_lldb_command
Run LLDB command.
debug_stack
Get backtrace.
debug_variables
Get frame variables.
build_device
Build for device.
build_run_device
Build, install, and launch on physical device. Preferred single-step run tool when defaults are set.
test_device
Test on device.
list_devices
List connected devices.
install_app_device
Install app on device.
launch_app_device
Launch app on device.
stop_app_device
Stop device app.
get_device_app_path
Get device built app path.
doctor
MCP environment info.
build_macos
Build macOS app.
build_run_macos
Build and run macOS app.
test_macos
Test macOS target.
launch_mac_app
Launch macOS app.
stop_mac_app
Stop macOS app.
get_mac_app_path
Get macOS built app path.
discover_projs
Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
list_schemes
List Xcode schemes.
show_build_settings
Show build settings.
get_app_bundle_id
Extract bundle id from .app.
get_mac_bundle_id
Extract bundle id from macOS .app.
scaffold_ios_project
Scaffold iOS project.
scaffold_macos_project
Scaffold macOS project.
session_show_defaults
Show current active defaults. Required before your first build/run/test call in a session — do not assume defaults are configured.
session_use_defaults_profile
Switch the active session defaults profile.
session_set_defaults
Set session defaults for the active profile, or for a specified profile and make it active.
session_clear_defaults
Clear session defaults for the active profile or a specified profile.
erase_sims
Erase simulator.
set_sim_location
Set sim location.
reset_sim_location
Reset sim location.
set_sim_appearance
Set sim appearance.
sim_statusbar
Set sim status bar network.
toggle_software_keyboard
Toggle the iOS Simulator software keyboard. Shows or hides the on-screen keyboard. Requires the simulator to be booted and Accessibility permission for the MCP host.
toggle_connect_hardware_keyboard
Toggle whether the iOS Simulator simulates a hardware keyboard connection. Disconnecting makes the on-screen keyboard appear for tap-based input. Requires the simulator to be booted and Accessibility permission for the MCP host.
boot_sim
Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
list_sims
List iOS simulators.
open_sim
Open the simulator frontend for visibility and manual workflows. Not required before simulator build-and-run (build_run_sim).
build_sim
Build for iOS sim (compile-only, no launch).
build_run_sim
Build, install, and launch on iOS Simulator, booting it when needed. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
test_sim
Test on iOS sim.
get_sim_app_path
Get sim built app path.
install_app_sim
Install app on sim.
launch_app_sim
Launch app on simulator. Runtime logs are captured automatically and the log file path is included in the response.
stop_app_sim
Stop sim app.
record_sim_video
Record sim video.
swift_package_build
swift package target build.
swift_package_test
Run swift package target tests.
swift_package_clean
swift package clean.
swift_package_run
swift package target run.
swift_package_stop
Stop SwiftPM run.
swift_package_list
List SwiftPM processes.
screenshot
Capture screenshot.
snapshot_ui
Capture a semantic rs/1 runtime UI snapshot with elementRef targets. Observe once, use tap for one target or batch for multiple same-screen targets, and refresh after navigation, scrolling, sheet changes, or obvious layout changes.
wait_for_ui
Poll rs/1 runtime UI snapshots until a selector-based UI predicate, selector-free textContains/gone text predicate, or selector-free settled predicate is satisfied, then record the latest snapshot. Prefer this after navigation or layout changes. Select with elementRef, identifier, label, role, or value when a selector is needed.
batch
tap
touch
Send touch down/up events to a UI element by elementRef from a current rs/1 runtime snapshot.
long_press
Long press a UI element by elementRef from a current rs/1 runtime snapshot.
swipe
withinElementRef is required; do not use elementRef. Optional distance is a normalized stroke fraction greater than 0 and up to 1. Example input: {"withinElementRef":"e7","direction":"up","distance":0.7}.
drag
gesture
Simulator gesture preset.
button
Press simulator hardware button.
key_press
Press one hardware key using an AXe HID key code. Prefer type_text for text entry. Common values include 40 Return/Enter, 42 Backspace, 43 Tab, and 44 Space.
key_sequence
Press hardware keys using AXe HID key codes. Prefer type_text for text entry. Common values include 40 Return/Enter, 42 Backspace, 43 Tab, and 44 Space.
type_text
clean
Clean build products.
manage-workflows
Workflows are groups of tools exposed by XcodeBuildMCP. By default, not all workflows (and therefore tools) are enabled; only simulator tools are enabled by default. Some workflows are mandatory and can't be disabled.
sync_xcode_defaults
Sync session defaults (scheme, simulator) from Xcode's current IDE selection.
xcode_ide_list_tools
Lists Xcode-IDE-only MCP capabilities (Use for: SwiftUI previews image capture, code snippet execution, issue Navigator/build logs, and window/tab context).
xcode_ide_call_tool
Call a remote Xcode IDE MCP tool.
xcode_tools_bridge_status
Show xcrun mcpbridge availability and proxy tool sync status.
xcode_tools_bridge_sync
One-shot connect + tools/list sync (manual retry; avoids background prompt spam).
xcode_tools_bridge_disconnect
Disconnect bridge and unregister proxied xcode_tools_* tools.
BEFORE YOU INSTALL
What to know first
Tools you get
Docs list 82; a default launch gives you 25.
Requires
- macOS 14.5 or later
- Xcode 16.x or later
- Node.js 18.x or later (not needed for the Homebrew install)
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g xcodebuildmcp@latestMCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": [
"-y",
"xcodebuildmcp@latest",
"mcp"
]
}
}
}
