How to Debug iOS App Crashes Using XcodeBuildMCP Simulator Tools

You can debug iOS app crashes programmatically using XcodeBuildMCP's deterministic RPC calls to boot simulators, build projects, interact with UI elements, and capture crash logs for post-mortem analysis.

The Dimillian/Skills repository provides the iOS Debugger Agent skill, which documents how to use XcodeBuildMCP (Modular Control Protocol) to script the entire iOS build-run-debug lifecycle. By leveraging these MCP tools to debug iOS app crashes using XcodeBuildMCP simulator tools, developers can automate crash reproduction and extract precise console output and UI state snapshots without manual Xcode intervention.

Understanding the XcodeBuildMCP Architecture

XcodeBuildMCP wraps Xcode's build system and the iOS Simulator into deterministic RPC calls. This protocol allows you to script every stage of debugging—from launching apps on booted devices to extracting structural UI descriptions and crash logs. According to the source code in ios-debugger-agent/SKILL.md, the MCP client exposes specific functions that handle simulator selection, session configuration, and log capture, enabling fully automated crash investigation.

Step-by-Step Crash Debugging Workflow

1. Select a Booted Simulator

Begin by enumerating available simulators using mcp__XcodeBuildMCP__list_sims. Filter for devices where the state field equals Booted to ensure you target an active simulator instance.

2. Configure the MCP Session

Call mcp__XcodeBuildMCP__session-set-defaults to establish your build parameters. This function accepts --scheme and --destination arguments, setting the default Xcode scheme and simulator target for subsequent operations.

3. Build and Launch the App

Execute mcp__XcodeBuildMCP__build_run_sim to compile the project and deploy it to the selected simulator. This single call reports compilation failures or early runtime aborts immediately, providing the first checkpoint for crash detection.

4. Verify Launch Success

Before triggering potential crashes, confirm the app is responsive using mcp__XcodeBuildMCP__describe_ui to extract the UI hierarchy, or mcp__XcodeBuildMCP__screenshot to capture a visual baseline. These verification steps ensure you are testing a properly launched instance.

5. Reproduce the Crash Through UI Interaction

Simulate user actions that lead to crashes using mcp__XcodeBuildMCP__tap, mcp__XcodeBuildMCP__type_text, or mcp__XcodeBuildMCP__gesture. These functions accept accessibility identifiers (--id), labels, or raw coordinates to target specific UI elements precisely.

6. Capture Crash Logs and Stack Traces

When the app terminates unexpectedly, retrieve the bundle identifier via mcp__XcodeBuildMCP__get_app_bundle_id, then initiate mcp__XcodeBuildMCP__start_sim_log_cap. After the crash occurs, execute mcp__XcodeBuildMCP__stop_sim_log_cap to extract the console output containing the stack trace and exception details.

Automated Crash Detection Script

Below is a complete bash workflow that implements the entire debug cycle. This script assumes the MCP client is available on your PATH and that you are executing from the root of your Xcode workspace:

# 1️⃣ List simulators and pick a booted one

BOOTED_SIM=$(mcp__XcodeBuildMCP__list_sims | jq -r '.simulators[] | select(.state=="Booted") | .udid')
echo "Using simulator: $BOOTED_SIM"

# 2️⃣ Set session defaults (replace MyScheme with your actual scheme)

mcp__XcodeBuildMCP__session-set-defaults \
    --scheme MyScheme \
    --destination "platform=iOS Simulator,id=$BOOTED_SIM"

# 3️⃣ Build and run the app on the simulator

BUILD_RESULT=$(mcp__XcodeBuildMCP__build_run_sim)
echo "$BUILD_RESULT"

# 4️⃣ Verify that the app launched

mcp__XcodeBuildMCP__describe_ui > ui_before.txt

# Optional visual check

mcp__XcodeBuildMCP__screenshot before_crash.png

# 5️⃣ Reproduce the crash – example: tap a button with accessibility identifier "crashButton"

mcp__XcodeBuildMCP__tap --id crashButton

# 6️⃣ Start capturing logs (bundle id is fetched dynamically)

APP_BUNDLE=$(mcp__XcodeBuildMCP__get_app_bundle_id)
mcp__XcodeBuildMCP__start_sim_log_cap --bundle-id "$APP_BUNDLE"

# Wait a moment for the crash to occur (adjust timeout as needed)

sleep 5

# 7️⃣ Stop log capture and filter for the crash stack trace

mcp__XcodeBuildMCP__stop_sim_log_cap --bundle-id "$APP_BUNDLE" > crash_log.txt
grep -i "fatal" -A20 crash_log.txt   # shows the exception & stack frames

Each command in this script corresponds to a specific stage in the crash debugging lifecycle, from environment setup to log extraction.

Key Source Files in the Repository

The Dimillian/Skills repository contains several critical files that define and document the XcodeBuildMCP implementation:

• ios-debugger-agent/SKILL.md: The primary documentation for the iOS Debugger Agent skill, containing exact RPC method names and their invocation sequences.
• README.md: Provides an overview of the repository's skill architecture and positions the iOS Debugger Agent as the entry point for automated debugging.
• macos-spm-app-packaging/assets/templates/bootstrap/Package.swift: Demonstrates the Swift Package Manager configuration used by skills that integrate with MCP build tools.
• macos-spm-app-packaging/assets/templates/bootstrap/Sources/MyApp/main.swift: Contains a minimal Swift entry point suitable for MCP-driven builds and quick sanity testing.

Summary

• XcodeBuildMCP provides deterministic RPC wrappers around Xcode's build system and iOS Simulator, enabling scripted debugging workflows.
• The iOS Debugger Agent skill in Dimillian/Skills documents the specific MCP calls required for automated crash investigation.
• Use mcp__XcodeBuildMCP__list_sims and mcp__XcodeBuildMCP__session-set-defaults to configure your target environment.
• Execute mcp__XcodeBuildMCP__build_run_sim to compile and launch, then verify with mcp__XcodeBuildMCP__describe_ui before testing.
• Reproduce crashes via mcp__XcodeBuildMCP__tap, type_text, or gesture, then capture logs using start_sim_log_cap and stop_sim_log_cap.
• This workflow is fully automatable and suitable for CI pipelines, providing reproducible crash detection and stack trace extraction.

Frequently Asked Questions

What is XcodeBuildMCP and how does it differ from standard xcodebuild?

XcodeBuildMCP (Modular Control Protocol) is an RPC-based wrapper that exposes Xcode's build system and simulator controls as deterministic, scriptable commands. Unlike standard xcodebuild, which requires manual parsing of output streams, MCP provides structured responses and direct UI manipulation capabilities through functions like mcp__XcodeBuildMCP__tap and mcp__XcodeBuildMCP__describe_ui.

How do I capture the exact stack trace when an iOS app crashes in the simulator?

First, retrieve your app's bundle identifier using mcp__XcodeBuildMCP__get_app_bundle_id, then execute mcp__XcodeBuildMCP__start_sim_log_cap before triggering the crash. After termination, run mcp__XcodeBuildMCP__stop_sim_log_cap to output the full console log, which contains the exception type, message, and symbolicated stack frames.

Can I automate iOS crash debugging in CI pipelines using these tools?

Yes. The MCP command sequence documented in ios-debugger-agent/SKILL.md is designed for automation, allowing you to script simulator booting, app deployment, UI interaction, and log capture. You can integrate the bash workflow into Jenkins, GitHub Actions, or other CI systems to detect regressions and verify crash fixes programmatically.

Which file contains the complete list of available MCP commands for iOS debugging?

The definitive reference is ios-debugger-agent/SKILL.md in the Dimillian/Skills repository. This file catalogs all available RPC methods, including mcp__XcodeBuildMCP__list_sims, mcp__XcodeBuildMCP__build_run_sim, and the log capture functions, along with their required parameters and expected return formats.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}