ios-debugger

ABOUTME: XcodeBuildMCP integration for building, running, and debugging iOS apps via CLI ABOUTME: Simulator control, UI interaction, log capture, screenshot automation iOS Debugger

When to Invoke

• Build/run iOS apps without Xcode UI
• Automate simulator interactions
• Capture app logs programmatically
• UI testing via CLI
• CI/CD iOS workflows

Capabilities

• Build and run on booted simulator
• Interact with simulator UI (tap, type, gestures)
• Capture and filter app logs
• Take screenshots
• Install/uninstall apps

Prerequisites

# Ensure XcodeBuildMCP is available
# Check if simulator is booted (pick <booted device> from this list, do not hardcode a model)
xcrun simctl list devices | grep Booted

# Boot simulator if needed
xcrun simctl boot "<booted device>"

Throughout this file, <booted device> is a placeholder: substitute the device name or UDID from xcrun simctl list devices | grep Booted.

Build and Run

# Build for simulator
xcodebuild -workspace MyApp.xcworkspace \
    -scheme MyApp \
    -sdk iphonesimulator \
    -destination 'platform=iOS Simulator,name=<booted device>' \
    build

# Install app on simulator
xcrun simctl install booted path/to/MyApp.app

# Launch app
xcrun simctl launch booted com.example.myapp

UI Interaction

simctl io does NOT do taps/typing/swipes (it only handles screenshot, recordVideo, enumerate, poll). For UI automation pick one of:

# Screenshot / screen recording (simctl's actual io surface)
xcrun simctl io booted screenshot screenshot.png
xcrun simctl io booted recordVideo demo.mov   # stop with Ctrl-C

# Taps/typing/gestures option 1: XCUITest (robust, accessibility-ID based)
xcodebuild test -workspace App.xcworkspace -scheme AppUITests \
    -destination 'platform=iOS Simulator,name=<booted device>'

# Taps/typing/gestures option 2: Meta's idb (brew install idb-companion; pip install fb-idb)
idb ui tap 200 400
idb ui text "Hello World"
idb ui swipe 200 600 200 200 --duration 0.5

If a command shape is not listed here, verify with xcrun simctl help io before using it (this file once shipped invented simctl io tap/type/swipe subcommands).

Log Capture

# Stream all logs from booted simulator
xcrun simctl spawn booted log stream --predicate 'processImagePath CONTAINS "MyApp"'

# Filter by subsystem
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.example.myapp"'

# Capture logs to file
xcrun simctl spawn booted log stream \
    --predicate 'processImagePath CONTAINS "MyApp"' \
    > app.log &

Common Workflows

Reset Simulator

# Erase all data
xcrun simctl erase "<booted device>"

# Shutdown and boot
xcrun simctl shutdown "<booted device>"
xcrun simctl boot "<booted device>"

Tips

• Always check simulator is booted before commands
• Use log stream predicates to filter noise
• Coordinate-based taps are fragile (prefer accessibility IDs in XCTest)
• Capture screenshots for visual regression tests
• Use xcrun simctl openurl to test deep links

Integration with Tests

# Run XCTests on simulator
xcodebuild test \
    -workspace App.xcworkspace \
    -scheme App \
    -destination 'platform=iOS Simulator,name=<booted device>' \
    -resultBundlePath TestResults.xcresult