Summary
XcodeBuildMCP provides an MCP server and CLI tool that enables AI agents to work with iOS and macOS projects by offering build automation and project inspection capabilities. The server exposes tools for interacting with Xcode projects, building targets, and managing the build process, allowing agents to programmatically interact with Xcode workflows on macOS. It solves the problem of giving AI assistants direct access to native iOS/macOS development tasks without requiring manual intervention or shell command composition.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Tools
Public tool metadata for what this MCP can expose to an agent.
71 tools
debug_attach_simAttach LLDB to a running iOS simulator app. Provide bundleId or pid, plus simulator defaults.5 params
Attach LLDB to a running iOS simulator app. Provide bundleId or pid, plus simulator defaults.
Parameters* required
bundleIdstringBundle identifier of the app to attach (e.g., 'com.example.MyApp')
continueOnAttachbooleanResume execution automatically after attaching (default: true)default: true
makeCurrentbooleanSet this debug session as the current session (default: true)default: true
pidintegerProcess ID to attach directly
waitForbooleanWait for the process to appear when attaching
debug_breakpoint_addAdd a breakpoint by file/line or function name for the active debug session.5 params
Add a breakpoint by file/line or function name for the active debug session.
Parameters* required
conditionstringOptional condition expression for the breakpoint
debugSessionIdstringDebug session ID to target (defaults to current session)
filestringSource file path for breakpoint
functionstringFunction name to break on
lineintegerLine number for breakpoint
debug_breakpoint_removeRemove a breakpoint by id for the active debug session.2 params
Remove a breakpoint by id for the active debug session.
Parameters* required
breakpointIdintegerBreakpoint id to remove
debugSessionIdstringDebug session ID to target (defaults to current session)
debug_continueResume execution in the active debug session or a specific debugSessionId.1 params
Resume execution in the active debug session or a specific debugSessionId.
Parameters* required
debugSessionIdstringDebug session ID to resume (defaults to current session)
debug_detachDetach the current debugger session or a specific debugSessionId.1 params
Detach the current debugger session or a specific debugSessionId.
Parameters* required
debugSessionIdstringDebug session ID to detach (defaults to current session)
debug_lldb_commandRun an arbitrary LLDB command within the active debug session.3 params
Run an arbitrary LLDB command within the active debug session.
Parameters* required
commandstringdebugSessionIdstringtimeoutMsintegerdebug_stackReturn a thread backtrace from the active debug session.3 params
Return a thread backtrace from the active debug session.
Parameters* required
debugSessionIdstringDebug session ID to target (defaults to current session)
maxFramesintegerMaximum frames to return
threadIndexintegerThread index for backtrace
debug_variablesReturn variables for a selected frame in the active debug session.2 params
Return variables for a selected frame in the active debug session.
Parameters* required
debugSessionIdstringDebug session ID to target (defaults to current session)
frameIndexintegerFrame index to inspect
build_deviceBuilds an app for a connected device.3 params
Builds an app for a connected device.
Parameters* required
derivedDataPathstringPath to derived data directory
extraArgsarrayAdditional arguments to pass to xcodebuild
preferXcodebuildbooleanPrefer xcodebuild over faster alternatives
cleanCleans build products with xcodebuild.4 params
Cleans build products with xcodebuild.
Parameters* required
derivedDataPathstringOptional: Path where derived data might be located
extraArgsarrayAdditional xcodebuild arguments
platformstringOptional: Platform to clean for (defaults to iOS). Choose from macOS, iOS, iOS Simulator, watchOS, watchOS Simulator, tvOS, tvOS Simulator, visionOS, visionOS Simulatorone of
macOS · iOS · iOS Simulator · watchOS · watchOS Simulator · tvOSpreferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system, useful for when incremental build system fails.
discover_projsScans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.3 params
Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
Parameters* required
maxDepthintegerOptional: Maximum directory depth to scan. Defaults to 5.
scanPathstringOptional: Path relative to workspace root to scan. Defaults to workspace root.
workspaceRootstringThe absolute path of the workspace root to scan within.
get_app_bundle_idExtracts the bundle identifier from an app bundle (.app) for any Apple platform (iOS, iPadOS, watchOS, tvOS, visionOS). IMPORTANT: You MUST provide the appPath parameter. Example: get_app_bundle_id({ appPath: '/path/to/your/app.app' })1 params
Extracts the bundle identifier from an app bundle (.app) for any Apple platform (iOS, iPadOS, watchOS, tvOS, visionOS). IMPORTANT: You MUST provide the appPath parameter. Example: get_app_bundle_id({ appPath: '/path/to/your/app.app' })
Parameters* required
appPathstringPath to the .app bundle to extract bundle ID from (full path to the .app directory)
get_device_app_pathRetrieves the built app path for a connected device.1 params
Retrieves the built app path for a connected device.
Parameters* required
platformstringTarget platform (defaults to iOS)one of
iOS · watchOS · tvOS · visionOSinstall_app_deviceInstalls an app on a connected device.1 params
Installs an app on a connected device.
Parameters* required
appPathstringPath to the .app bundle to install (full path to the .app directory)
launch_app_deviceLaunches an app on a connected device.1 params
Launches an app on a connected device.
Parameters* required
bundleIdstringBundle identifier of the app to launch (e.g., "com.example.MyApp")
list_devicesLists connected physical Apple devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro) with their UUIDs, names, and connection status. Use this to discover physical devices for testing.
Lists connected physical Apple devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro) with their UUIDs, names, and connection status. Use this to discover physical devices for testing.
No parameter schema in public metadata yet.
list_schemesLists schemes for a project or workspace.
Lists schemes for a project or workspace.
No parameter schema in public metadata yet.
show_build_settingsShows xcodebuild build settings.
Shows xcodebuild build settings.
No parameter schema in public metadata yet.
start_device_log_capStarts log capture on a connected device.1 params
Starts log capture on a connected device.
Parameters* required
bundleIdstringBundle identifier of the app to launch and capture logs for.
stop_app_deviceStops a running app on a connected device.1 params
Stops a running app on a connected device.
Parameters* required
processIdnumberProcess ID (PID) of the app to stop
stop_device_log_capStops an active Apple device log capture session and returns the captured logs.1 params
Stops an active Apple device log capture session and returns the captured logs.
Parameters* required
logSessionIdstringThe session ID returned by start_device_log_cap.
test_deviceRuns tests on a physical Apple device.5 params
Runs tests on a physical Apple device.
Parameters* required
derivedDataPathstringPath to derived data directory
extraArgsarrayAdditional arguments to pass to xcodebuild
platformstringTarget platform (defaults to iOS)one of
iOS · watchOS · tvOS · visionOSpreferXcodebuildbooleanPrefer xcodebuild over faster alternatives
testRunnerEnvobjectEnvironment variables to pass to the test runner (TEST_RUNNER_ prefix added automatically)
doctorProvides comprehensive information about the MCP server environment, available dependencies, and configuration status.1 params
Provides comprehensive information about the MCP server environment, available dependencies, and configuration status.
Parameters* required
enabledbooleanOptional: dummy parameter to satisfy MCP protocol
start_sim_log_capStarts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.2 params
Starts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.
Parameters* required
bundleIdstringBundle identifier of the app to capture logs for.
captureConsolebooleanWhether to capture console output (requires app relaunch).
stop_sim_log_capStops an active simulator log capture session and returns the captured logs.1 params
Stops an active simulator log capture session and returns the captured logs.
Parameters* required
logSessionIdstringThe session ID returned by start_sim_log_cap.
build_macosBuilds a macOS app.3 params
Builds a macOS app.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system
build_run_macosBuilds and runs a macOS app.3 params
Builds and runs a macOS app.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system
get_mac_app_pathRetrieves the built macOS app bundle path.2 params
Retrieves the built macOS app bundle path.
Parameters* required
derivedDataPathstringPath to derived data directory
extraArgsarrayAdditional arguments to pass to xcodebuild
get_mac_bundle_idExtracts the bundle identifier from a macOS app bundle (.app). IMPORTANT: You MUST provide the appPath parameter. Example: get_mac_bundle_id({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_get_macos_bundle_id.1 params
Extracts the bundle identifier from a macOS app bundle (.app). IMPORTANT: You MUST provide the appPath parameter. Example: get_mac_bundle_id({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_get_macos_bundle_id.
Parameters* required
appPathstringPath to the macOS .app bundle to extract bundle ID from (full path to the .app directory)
launch_mac_appLaunches a macOS application. IMPORTANT: You MUST provide the appPath parameter. Example: launch_mac_app({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.2 params
Launches a macOS application. IMPORTANT: You MUST provide the appPath parameter. Example: launch_mac_app({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.
Parameters* required
appPathstringPath to the macOS .app bundle to launch (full path to the .app directory)
argsarrayAdditional arguments to pass to the app
stop_mac_appStops a running macOS application. Can stop by app name or process ID.2 params
Stops a running macOS application. Can stop by app name or process ID.
Parameters* required
appNamestringName of the application to stop (e.g., "Calculator" or "MyApp")
processIdnumberProcess ID (PID) of the application to stop
test_macosRuns tests for a macOS target.4 params
Runs tests for a macOS target.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system
testRunnerEnvobjectEnvironment variables to pass to the test runner (TEST_RUNNER_ prefix added automatically)
scaffold_ios_projectScaffold a new iOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper iOS configuration.11 params
Scaffold a new iOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper iOS configuration.
Parameters* required
bundleIdentifierstringBundle identifier (e.g., com.example.myapp). If not provided, will use com.example.projectname
currentProjectVersionstringBuild number (e.g., 1, 42, 100). If not provided, will use 1
customizeNamesbooleanWhether to customize project names and identifiers. Default is true.default: true
deploymentTargetstringiOS deployment target (e.g., 18.4, 17.0). If not provided, will use 18.4
displayNamestringApp display name (shown on home screen/dock). If not provided, will use projectName
marketingVersionstringMarketing version (e.g., 1.0, 2.1.3). If not provided, will use 1.0
outputPathstringPath where the project should be created
projectNamestringName of the new project
supportedOrientationsarraySupported orientations for iPhone
supportedOrientationsIpadarraySupported orientations for iPad
targetedDeviceFamilyarrayTargeted device families
scaffold_macos_projectScaffold a new macOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper macOS configuration.8 params
Scaffold a new macOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper macOS configuration.
Parameters* required
bundleIdentifierstringBundle identifier (e.g., com.example.myapp). If not provided, will use com.example.projectname
currentProjectVersionstringBuild number (e.g., 1, 42, 100). If not provided, will use 1
customizeNamesbooleanWhether to customize project names and identifiers. Default is true.default: true
deploymentTargetstringmacOS deployment target (e.g., 15.4, 14.0). If not provided, will use 15.4
displayNamestringApp display name (shown on home screen/dock). If not provided, will use projectName
marketingVersionstringMarketing version (e.g., 1.0, 2.1.3). If not provided, will use 1.0
outputPathstringPath where the project should be created
projectNamestringName of the new project
session-clear-defaultsClear selected or all session defaults.2 params
Clear selected or all session defaults.
Parameters* required
allbooleankeysarraysession-set-defaultsSet the session defaults needed by many tools. Most tools require one or more session defaults to be set before they can be used. Agents should set all relevant defaults up front in a single call (e.g., project/workspace, scheme, simulator or device ID, useLatestOS) to avoid i...10 params
Set the session defaults needed by many tools. Most tools require one or more session defaults to be set before they can be used. Agents should set all relevant defaults up front in a single call (e.g., project/workspace, scheme, simulator or device ID, useLatestOS) to avoid i...
Parameters* required
archstringTarget architecture for macOS builds.one of
arm64 · x86_64configurationstringBuild configuration, e.g. Debug or Release.
deviceIdstringPhysical device ID for device workflows.
projectPathstringXcode project (.xcodeproj) path. Mutually exclusive with workspacePath. Required for most build/test tools when workspacePath is not set.
schemestringXcode scheme. Required by most build/test tools. Use list_schemes to discover available schemes before setting.
simulatorIdstringSimulator UUID for simulator workflows. Preferred over simulatorName when both are provided.
simulatorNamestringSimulator device name for simulator workflows. If simulatorId is also provided, simulatorId is preferred and simulatorName is ignored.
suppressWarningsbooleanWhen true, warning messages are filtered from build output to conserve context
useLatestOSbooleanWhen true, prefer the latest available OS for simulatorName lookups.
workspacePathstringXcode workspace (.xcworkspace) path. Mutually exclusive with projectPath. Required for most build/test tools when projectPath is not set.
session-show-defaultsShow current session defaults.
Show current session defaults.
No parameter schema in public metadata yet.
boot_simBoots an iOS simulator.
Boots an iOS simulator.
No parameter schema in public metadata yet.
build_run_simBuilds and runs an app on an iOS simulator.3 params
Builds and runs an app on an iOS simulator.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system, useful for when incremental build system fails.
build_simBuilds an app for an iOS simulator.3 params
Builds an app for an iOS simulator.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system, useful for when incremental build system fails.
describe_uiGets entire view hierarchy with precise frame coordinates (x, y, width, height) for all visible elements. Use this before UI interactions or after layout changes - do NOT guess coordinates from screenshots. Returns JSON tree with frame data for accurate automation. Requires th...
Gets entire view hierarchy with precise frame coordinates (x, y, width, height) for all visible elements. Use this before UI interactions or after layout changes - do NOT guess coordinates from screenshots. Returns JSON tree with frame data for accurate automation. Requires th...
No parameter schema in public metadata yet.
get_sim_app_pathRetrieves the built app path for an iOS simulator.1 params
Retrieves the built app path for an iOS simulator.
Parameters* required
platformstringTarget simulator platform (Required)one of
iOS Simulator · watchOS Simulator · tvOS Simulator · visionOS Simulatorinstall_app_simInstalls an app in an iOS simulator.1 params
Installs an app in an iOS simulator.
Parameters* required
appPathstringPath to the .app bundle to install (full path to the .app directory)
launch_app_logs_simLaunches an app in an iOS simulator and captures its logs.2 params
Launches an app in an iOS simulator and captures its logs.
Parameters* required
argsarrayAdditional arguments to pass to the app
bundleIdstringBundle identifier of the app to launch (e.g., 'com.example.MyApp')
launch_app_simLaunches an app in an iOS simulator.2 params
Launches an app in an iOS simulator.
Parameters* required
argsarrayAdditional arguments to pass to the app
bundleIdstringBundle identifier of the app to launch (e.g., 'com.example.MyApp')
list_simsLists available iOS simulators with their UUIDs.1 params
Lists available iOS simulators with their UUIDs.
Parameters* required
enabledbooleanOptional flag to enable the listing operation.
open_simOpens the iOS Simulator app.
Opens the iOS Simulator app.
No parameter schema in public metadata yet.
record_sim_videoStarts or stops video capture for an iOS simulator.4 params
Starts or stops video capture for an iOS simulator.
Parameters* required
fpsintegerFrames per second (default 30)
outputFilestringDestination MP4 path to move the recorded video to on stop
startbooleanStart recording if true
stopbooleanStop recording if true
screenshotCaptures screenshot for visual verification. For UI coordinates, use describe_ui instead (don't determine coordinates from screenshots).
Captures screenshot for visual verification. For UI coordinates, use describe_ui instead (don't determine coordinates from screenshots).
No parameter schema in public metadata yet.
stop_app_simStops an app running in an iOS simulator.1 params
Stops an app running in an iOS simulator.
Parameters* required
bundleIdstringBundle identifier of the app to stop (e.g., 'com.example.MyApp')
test_simRuns tests on an iOS simulator.4 params
Runs tests on an iOS simulator.
Parameters* required
derivedDataPathstringPath where build products and other derived data will go
extraArgsarrayAdditional xcodebuild arguments
preferXcodebuildbooleanIf true, prefers xcodebuild over the experimental incremental build system, useful for when incremental build system fails.
testRunnerEnvobjectEnvironment variables to pass to the test runner (TEST_RUNNER_ prefix added automatically)
erase_simsErases a simulator by UDID.1 params
Erases a simulator by UDID.
Parameters* required
shutdownFirstbooleanIf true, shuts down the simulator before erasing.
reset_sim_locationResets the simulator's location to default.
Resets the simulator's location to default.
No parameter schema in public metadata yet.
set_sim_appearanceSets the appearance mode (dark/light) of an iOS simulator.1 params
Sets the appearance mode (dark/light) of an iOS simulator.
Parameters* required
modestringThe appearance mode to set (either "dark" or "light")one of
dark · lightset_sim_locationSets a custom GPS location for the simulator.2 params
Sets a custom GPS location for the simulator.
Parameters* required
latitudenumberThe latitude for the custom location.
longitudenumberThe longitude for the custom location.
sim_statusbarSets the data network indicator in the iOS simulator status bar. Use "clear" to reset all overrides, or specify a network type (hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc).1 params
Sets the data network indicator in the iOS simulator status bar. Use "clear" to reset all overrides, or specify a network type (hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc).
Parameters* required
dataNetworkstringData network type to display in status bar. Use "clear" to reset all overrides. Valid values: clear, hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc.one of
clear · hide · wifi · 3g · 4g · lteswift_package_buildBuilds a Swift Package with swift build5 params
Builds a Swift Package with swift build
Parameters* required
architecturesarrayTarget architectures to build for
configurationstringSwift package configuration (debug, release)one of
debug · releasepackagePathstringPath to the Swift package root (Required)
parseAsLibrarybooleanBuild as library instead of executable
targetNamestringOptional target to build
swift_package_cleanCleans Swift Package build artifacts and derived data1 params
Cleans Swift Package build artifacts and derived data
Parameters* required
packagePathstringPath to the Swift package root (Required)
swift_package_listLists currently running Swift Package processes
Lists currently running Swift Package processes
No parameter schema in public metadata yet.
swift_package_runRuns an executable target from a Swift Package with swift run7 params
Runs an executable target from a Swift Package with swift run
Parameters* required
argumentsarrayArguments to pass to the executable
backgroundbooleanRun in background and return immediately (default: false)
configurationstringBuild configuration: 'debug' (default) or 'release'one of
debug · releaseexecutableNamestringName of executable to run (defaults to package name)
packagePathstringPath to the Swift package root (Required)
parseAsLibrarybooleanAdd -parse-as-library flag for @main support (default: false)
timeoutnumberTimeout in seconds (default: 30, max: 300)
swift_package_stopStops a running Swift Package executable started with swift_package_run1 params
Stops a running Swift Package executable started with swift_package_run
Parameters* required
pidnumberProcess ID (PID) of the running executable
swift_package_testRuns tests for a Swift Package with swift test7 params
Runs tests for a Swift Package with swift test
Parameters* required
configurationstringSwift package configuration (debug, release)one of
debug · releasefilterstringFilter tests by name (regex pattern)
packagePathstringPath to the Swift package root (Required)
parallelbooleanRun tests in parallel (default: true)
parseAsLibrarybooleanAdd -parse-as-library flag for @main support (default: false)
showCodecovbooleanShow code coverage (default: false)
testProductstringOptional specific test product to run
buttonPress hardware button on iOS simulator. Supported buttons: apple-pay, home, lock, side-button, siri2 params
Press hardware button on iOS simulator. Supported buttons: apple-pay, home, lock, side-button, siri
Parameters* required
buttonTypestringone of
apple-pay · home · lock · side-button · siridurationnumbergesturePerform gesture on iOS simulator using preset gestures: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge7 params
Perform gesture on iOS simulator using preset gestures: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge
Parameters* required
deltanumberOptional: Distance to move in pixels.
durationnumberOptional: Duration of the gesture in seconds.
postDelaynumberOptional: Delay after completing the gesture in seconds.
preDelaynumberOptional: Delay before starting the gesture in seconds.
presetstringThe gesture preset to perform. Must be one of: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge.one of
scroll-up · scroll-down · scroll-left · scroll-right · swipe-from-left-edge · swipe-from-right-edgescreenHeightintegerOptional: Screen height in pixels. Used for gesture calculations. Auto-detected if not provided.
screenWidthintegerOptional: Screen width in pixels. Used for gesture calculations. Auto-detected if not provided.
key_pressPress a single key by keycode on the simulator. Common keycodes: 40=Return, 42=Backspace, 43=Tab, 44=Space, 58-67=F1-F10.2 params
Press a single key by keycode on the simulator. Common keycodes: 40=Return, 42=Backspace, 43=Tab, 44=Space, 58-67=F1-F10.
Parameters* required
durationnumberkeyCodeintegerkey_sequencePress key sequence using HID keycodes on iOS simulator with configurable delay2 params
Press key sequence using HID keycodes on iOS simulator with configurable delay
Parameters* required
delaynumberkeyCodesarraylong_pressLong press at specific coordinates for given duration (ms). Use describe_ui for precise coordinates (don't guess from screenshots).3 params
Long press at specific coordinates for given duration (ms). Use describe_ui for precise coordinates (don't guess from screenshots).
Parameters* required
durationnumberxintegeryintegerswipeSwipe from one point to another. Use describe_ui for precise coordinates (don't guess from screenshots). Supports configurable timing.8 params
Swipe from one point to another. Use describe_ui for precise coordinates (don't guess from screenshots). Supports configurable timing.
Parameters* required
deltanumberdurationnumberpostDelaynumberpreDelaynumberx1integerx2integery1integery2integertapTap at specific coordinates or target elements by accessibility id or label. Use describe_ui to get precise element coordinates prior to using x/y parameters (don't guess from screenshots). Supports optional timing delays.6 params
Tap at specific coordinates or target elements by accessibility id or label. Use describe_ui to get precise element coordinates prior to using x/y parameters (don't guess from screenshots). Supports optional timing delays.
Parameters* required
idstringlabelstringpostDelaynumberpreDelaynumberxintegeryintegertouchPerform touch down/up events at specific coordinates. Use describe_ui for precise coordinates (don't guess from screenshots).5 params
Perform touch down/up events at specific coordinates. Use describe_ui for precise coordinates (don't guess from screenshots).
Parameters* required
delaynumberdownbooleanupbooleanxintegeryintegertype_textType text (supports US keyboard characters). Use describe_ui to find text field, tap to focus, then type.1 params
Type text (supports US keyboard characters). Use describe_ui to find text field, tap to focus, then type.
Parameters* required
textstring
A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
Installation
XcodeBuildMCP ships as a single package with two modes: a CLI for direct terminal use and an MCP server for AI coding agents. Either install method gives you both.
Option A — Homebrew
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp
Option B — npm (Node.js 18+)
npm install -g xcodebuildmcp@latest
Verify either install:
xcodebuildmcp --help
Connect your MCP client
Drop-in config snippets for Cursor, Claude Code, Codex, can be found in the official docs page MCP Clients. Most clients can also run the MCP server on demand via npx -y xcodebuildmcp@latest mcp without a global install.
Requirements
- macOS 14.5 or later
- Xcode 16.x or later
- Node.js 18.x or later (not required for Homebrew installation)
Skills
XcodeBuildMCP now includes two optional agent skills:
-
MCP Skill: Primes the agent with instructions on how to use the MCP server's tools (optional when using the MCP server).
-
CLI Skill: Primes the agent with instructions on how to navigate the CLI (recommended when using the CLI).
To install with a global binary:
xcodebuildmcp init
Or install directly via npx without a global install:
npx -y xcodebuildmcp@latest init
For further information on installing skills, see Agent Skills.
Notes
- XcodeBuildMCP requests xcodebuild to skip macro validation to avoid errors when building projects that use Swift Macros.
- Device tools require code signing to be configured in Xcode. See Device Code Signing.
Privacy
XcodeBuildMCP uses Sentry for internal runtime error telemetry only. For details and opt-out instructions, see Privacy & Telemetry.
CLI
XcodeBuildMCP provides a unified command-line interface. The mcp subcommand starts the MCP server, while all other commands provide direct terminal access to tools:
# Install globally
npm install -g xcodebuildmcp@latest
# Start the MCP server (for MCP clients)
xcodebuildmcp mcp
# List available tools
xcodebuildmcp tools
# Build for simulator
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
# Prepare portable test products without running tests
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17" --build-for-testing --test-products-path ./MyApp.xctestproducts
# Run previously prepared test products
xcodebuildmcp simulator test --test-products-path ./MyApp.xctestproducts --simulator-name "iPhone 17"
Check for updates and upgrade in place:
xcodebuildmcp upgrade --check
xcodebuildmcp upgrade --yes
The CLI uses a per-workspace daemon for stateful operations (log capture, debugging, etc.) that auto-starts when needed. See the CLI guide for full documentation.
Documentation
- Installation: https://xcodebuildmcp.com/docs/installation
- Setup: https://xcodebuildmcp.com/docs/setup
- MCP clients: https://xcodebuildmcp.com/docs/clients
- CLI usage: https://xcodebuildmcp.com/docs/cli
- Configuration and options: https://xcodebuildmcp.com/docs/configuration
- Tools reference: https://xcodebuildmcp.com/docs/tools
- Troubleshooting: https://xcodebuildmcp.com/docs/troubleshooting
- Privacy: https://xcodebuildmcp.com/docs/privacy
- Skills: https://xcodebuildmcp.com/docs/skills
- Contributing: https://xcodebuildmcp.com/docs/contributing
Licence
This project is licensed under the MIT License - see the LICENSE file for details. For third-party licensing notices see the THIRD_PARTY_LICENSES file for details. For npm package attributions see the THIRD_PARTY_PACKAGE_LICENSES file for details.
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Configuration
INCREMENTAL_BUILDS_ENABLEDdefault: falseEnable experimental xcodemake incremental builds (true/false or 1/0).
XCODEBUILDMCP_ENABLED_WORKFLOWSComma-separated list of workflows to load at startup (e.g., 'simulator,device,project-discovery').
XCODEBUILDMCP_SENTRY_DISABLEDdefault: falseDisable Sentry error reporting (preferred flag).
XCODEBUILDMCP_DEBUGdefault: falseEnable verbose debug logging from the server.
Categories
Registryactive
Packagexcodebuildmcp
TransportSTDIO
UpdatedJun 2, 2026
