bjesuiter/xcode

Xcode Build MCP

Build, test, run, and manage Xcode projects and Swift packages via the XcodeBuildMCP server.

When to Use

• User wants to build an iOS/macOS/watchOS/tvOS/visionOS app
• User wants to run tests on simulator or device
• User wants to launch an app on simulator or device
• User mentions "xcodebuild", "swift build", "swift test"
• User wants to scaffold a new iOS/macOS project
• User wants to interact with iOS simulator (tap, type, screenshot)
• User wants to capture logs from simulator or device
• User wants to discover Xcode projects in a directory

Quick Reference

All tools are called via mcporter using the XcodeBuildMCP server:

bunx mcporter call --stdio "xcodebuildmcp" <tool_name> [args...]

Assumes mcporter and xcodebuildmcp are installed globally; bunx runs the installed binaries and does not fetch them.

Session Defaults (IMPORTANT - Set First!)

Before using most build/test tools, you MUST set session defaults:

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  projectPath="/path/to/Project.xcodeproj" \
  scheme="MyApp" \
  simulatorName="iPhone 16"

Or for a workspace:

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  workspacePath="/path/to/Project.xcworkspace" \
  scheme="MyApp" \
  simulatorId="DEVICE_UDID"

Check current defaults:

bunx mcporter call --stdio "xcodebuildmcp" session-show-defaults

Clear defaults:

bunx mcporter call --stdio "xcodebuildmcp" session-clear-defaults all=true

Discovery Tools

Find Xcode Projects

bunx mcporter call --stdio "xcodebuildmcp" discover_projs workspaceRoot="$(pwd)"

List Schemes

bunx mcporter call --stdio "xcodebuildmcp" list_schemes

Doctor (Check Environment)

bunx mcporter call --stdio "xcodebuildmcp" doctor

Simulator Tools

List Simulators

bunx mcporter call --stdio "xcodebuildmcp" list_sims

Boot Simulator

bunx mcporter call --stdio "xcodebuildmcp" boot_sim

Open Simulator App

bunx mcporter call --stdio "xcodebuildmcp" open_sim

Build for Simulator

bunx mcporter call --stdio "xcodebuildmcp" build_sim

Build and Run on Simulator

bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

Run Tests on Simulator

bunx mcporter call --stdio "xcodebuildmcp" test_sim

Get Built App Path (Simulator)

bunx mcporter call --stdio "xcodebuildmcp" get_sim_app_path platform="iOS Simulator"

Install App on Simulator

bunx mcporter call --stdio "xcodebuildmcp" install_app_sim appPath="/path/to/App.app"

Launch App on Simulator

bunx mcporter call --stdio "xcodebuildmcp" launch_app_sim bundleId="com.example.MyApp"

Stop App on Simulator

bunx mcporter call --stdio "xcodebuildmcp" stop_app_sim bundleId="com.example.MyApp"

Simulator UI Automation

Take Screenshot

bunx mcporter call --stdio "xcodebuildmcp" screenshot

Describe UI (Get View Hierarchy)

Gets precise frame coordinates for all visible elements - USE THIS before any UI interactions:

bunx mcporter call --stdio "xcodebuildmcp" describe_ui

Tap

# Tap by coordinates (use describe_ui first to get coordinates)
bunx mcporter call --stdio "xcodebuildmcp" tap x=100 y=200

# Tap by accessibility ID
bunx mcporter call --stdio "xcodebuildmcp" tap id="myButton"

# Tap by label
bunx mcporter call --stdio "xcodebuildmcp" tap label="Submit"

Long Press

bunx mcporter call --stdio "xcodebuildmcp" long_press x=100 y=200 duration=1000

Swipe

bunx mcporter call --stdio "xcodebuildmcp" swipe x1=100 y1=400 x2=100 y2=100

Gesture Presets

bunx mcporter call --stdio "xcodebuildmcp" gesture preset="scroll-down"
# Presets: scroll-up, scroll-down, scroll-left, scroll-right, 
#          swipe-from-left-edge, swipe-from-right-edge, 
#          swipe-from-top-edge, swipe-from-bottom-edge

Type Text

bunx mcporter call --stdio "xcodebuildmcp" type_text text="Hello World"

Press Button

bunx mcporter call --stdio "xcodebuildmcp" button buttonType="home"
# Types: apple-pay, home, lock, side-button, siri

Key Press

bunx mcporter call --stdio "xcodebuildmcp" key_press keyCode=40  # Return key
# Common: 40=Return, 42=Backspace, 43=Tab, 44=Space

Simulator Settings

Set Appearance (Dark/Light Mode)

bunx mcporter call --stdio "xcodebuildmcp" set_sim_appearance mode="dark"

Set Location

bunx mcporter call --stdio "xcodebuildmcp" set_sim_location latitude=37.7749 longitude=-122.4194

Reset Location

bunx mcporter call --stdio "xcodebuildmcp" reset_sim_location

Set Status Bar Network

bunx mcporter call --stdio "xcodebuildmcp" sim_statusbar dataNetwork="5g"
# Options: clear, hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc

Erase Simulator

bunx mcporter call --stdio "xcodebuildmcp" erase_sims shutdownFirst=true

Simulator Log Capture

Start Log Capture

bunx mcporter call --stdio "xcodebuildmcp" start_sim_log_cap bundleId="com.example.MyApp"
# Returns a logSessionId

Stop Log Capture

bunx mcporter call --stdio "xcodebuildmcp" stop_sim_log_cap logSessionId="SESSION_ID"

Video Recording

Start Recording

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video start=true

Stop Recording

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video stop=true outputFile="/path/to/output.mp4"

Physical Device Tools

List Connected Devices

bunx mcporter call --stdio "xcodebuildmcp" list_devices

Build for Device

bunx mcporter call --stdio "xcodebuildmcp" build_device

Test on Device

bunx mcporter call --stdio "xcodebuildmcp" test_device

Install App on Device

bunx mcporter call --stdio "xcodebuildmcp" install_app_device appPath="/path/to/App.app"

Launch App on Device

bunx mcporter call --stdio "xcodebuildmcp" launch_app_device bundleId="com.example.MyApp"

Stop App on Device

bunx mcporter call --stdio "xcodebuildmcp" stop_app_device processId=12345

Device Log Capture

# Start
bunx mcporter call --stdio "xcodebuildmcp" start_device_log_cap bundleId="com.example.MyApp"

# Stop
bunx mcporter call --stdio "xcodebuildmcp" stop_device_log_cap logSessionId="SESSION_ID"

macOS Tools

Build macOS App

bunx mcporter call --stdio "xcodebuildmcp" build_macos

Build and Run macOS App

bunx mcporter call --stdio "xcodebuildmcp" build_run_macos

Test macOS App

bunx mcporter call --stdio "xcodebuildmcp" test_macos

Get macOS App Path

bunx mcporter call --stdio "xcodebuildmcp" get_mac_app_path

Launch macOS App

bunx mcporter call --stdio "xcodebuildmcp" launch_mac_app appPath="/path/to/App.app"

Stop macOS App

bunx mcporter call --stdio "xcodebuildmcp" stop_mac_app appName="MyApp"

Swift Package Tools

Build Package

bunx mcporter call --stdio "xcodebuildmcp" swift_package_build packagePath="$(pwd)"

Test Package

bunx mcporter call --stdio "xcodebuildmcp" swift_package_test packagePath="$(pwd)"

Run Package Executable

bunx mcporter call --stdio "xcodebuildmcp" swift_package_run packagePath="$(pwd)"

Clean Package

bunx mcporter call --stdio "xcodebuildmcp" swift_package_clean packagePath="$(pwd)"

List Running Packages

bunx mcporter call --stdio "xcodebuildmcp" swift_package_list

Stop Package Process

bunx mcporter call --stdio "xcodebuildmcp" swift_package_stop pid=12345

Project Scaffolding

Create New iOS Project

bunx mcporter call --stdio "xcodebuildmcp" scaffold_ios_project \
  projectName="MyApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.myapp"

Create New macOS Project

bunx mcporter call --stdio "xcodebuildmcp" scaffold_macos_project \
  projectName="MyMacApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.mymacapp"

Utility Tools

Clean Build

bunx mcporter call --stdio "xcodebuildmcp" clean

Show Build Settings

bunx mcporter call --stdio "xcodebuildmcp" show_build_settings

Get Bundle ID from App

bunx mcporter call --stdio "xcodebuildmcp" get_app_bundle_id appPath="/path/to/App.app"

Typical Workflows

Build and Test iOS App on Simulator

# 1. Discover projects
bunx mcporter call --stdio "xcodebuildmcp" discover_projs workspaceRoot="$(pwd)"

# 2. List simulators
bunx mcporter call --stdio "xcodebuildmcp" list_sims

# 3. Set session defaults
bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  projectPath="$(pwd)/MyApp.xcodeproj" \
  scheme="MyApp" \
  simulatorName="iPhone 16"

# 4. Build and run
bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

# 5. Run tests
bunx mcporter call --stdio "xcodebuildmcp" test_sim

UI Testing Flow

# 1. Build and launch app
bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

# 2. Get UI hierarchy (ALWAYS do this before interacting)
bunx mcporter call --stdio "xcodebuildmcp" describe_ui

# 3. Take screenshot for visual reference
bunx mcporter call --stdio "xcodebuildmcp" screenshot

# 4. Interact with elements using coordinates from describe_ui
bunx mcporter call --stdio "xcodebuildmcp" tap x=187 y=423

# 5. Type text
bunx mcporter call --stdio "xcodebuildmcp" type_text text="[email protected]"

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | No project/workspace set | Session defaults not configured | Run session-set-defaults first | | Simulator not found | Invalid simulator name | Run list_sims to get valid names | | Build failed | Code errors or config issues | Check build output, run doctor | | App not installed | Build didn't complete | Run build_sim before launch_app_sim |

Tips

1. Always set session defaults first - Most tools require project/scheme/simulator to be set
2. Use describe_ui before UI interactions - Never guess coordinates from screenshots
3. Check doctor for environment issues - Run doctor if tools aren't working
4. Use preferXcodebuild=true if incremental builds fail - Falls back to standard xcodebuild