# How to Debug iOS App Crashes Using XcodeBuildMCP Simulator Tools

> Debug iOS app crashes programmatically with XcodeBuildMCP. Learn to boot simulators, build projects, and capture crash logs for post-mortem analysis to resolve issues efficiently.

- Repository: [Thomas Ricouard/Skills](https://github.com/Dimillian/Skills)
- Tags: how-to-guide
- Published: 2026-04-01

---

**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`](https://github.com/Dimillian/Skills/blob/main/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:

```bash

# 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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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`](https://github.com/Dimillian/Skills/blob/main/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.