How to Capture and Analyze iOS Simulator Logs with XcodeBuildMCP

The iOS Debugger Agent in the Dimillian/Skills repository orchestrates log collection by detecting a booted simulator, configuring an MCP session with your Xcode project, and streaming console output through XcodeBuildMCP's start/stop log capture functions.

The XcodeBuildMCP toolset provides a declarative interface for interacting with iOS simulators without executing arbitrary shell commands. According to the Dimillian/Skills source code, you can capture and analyze iOS simulator logs through a three-phase workflow defined in ios-debugger-agent/SKILL.md that leverages pure-function MCP descriptors to stream device console data into a queryable buffer.

Detect a Booted Simulator

Before capturing logs, identify which simulator is currently running. The mcp__XcodeBuildMCP__list_sims function returns all available simulators as a JSON array, allowing you to select the one where state equals Booted.

sims = mcp__XcodeBuildMCP__list_sims()
booted = next(s for s in sims if s["state"] == "Booted")
sim_id = booted["udid"]

Each simulator object contains a udid, state, and runtime property, enabling precise targeting of active instances.

Configure the MCP Session

Initialize the MCP environment using mcp__XcodeBuildMCP__session_set_defaults to specify your project configuration and target simulator. This function accepts projectPath (or workspacePath), scheme, and the simulatorId retrieved in the previous step.

mcp__XcodeBuildMCP__session_set_defaults(
    projectPath="/path/to/MyApp.xcodeproj",
    scheme="MyApp",
    simulatorId=sim_id,
    configuration="Debug",
    useLatestOS=True
)

Optional parameters like configuration: "Debug" and useLatestOS: true ensure reproducible builds across different macOS hosts with Xcode installed.

Start and Stop Log Capture

Once your app is running, stream console output by calling mcp__XcodeBuildMCP__start_sim_log_cap with the app's bundle identifier. This returns a log handle that references the streaming buffer.

bundle_id = mcp__XcodeBuildMCP__get_app_bundle_id()
log_handle = mcp__XcodeBuildMCP__start_sim_log_cap(bundle_id)

After interacting with the UI or completing your test scenario, terminate the stream using mcp__XcodeBuildMCP__stop_sim_log_cap, which returns the complete captured output as a text string.

raw_log = mcp__XcodeBuildMCP__stop_sim_log_cap(log_handle)

Complete Implementation Example

The following end-to-end example demonstrates the full workflow implemented in the iOS Debugger Agent, from simulator detection through log analysis:

# Phase 1: Detect booted simulator

sims = mcp__XcodeBuildMCP__list_sims()
booted = next(s for s in sims if s["state"] == "Booted")
sim_id = booted["udid"]

# Phase 2: Configure session

mcp__XcodeBuildMCP__session_set_defaults(
    projectPath="/path/to/MyApp.xcodeproj",
    scheme="MyApp",
    simulatorId=sim_id,
    configuration="Debug",
    useLatestOS=True
)

# Phase 3: Build and verify launch

mcp__XcodeBuildMCP__build_run_sim()
ui = mcp__XcodeBuildMCP__describe_ui()

# Phase 4: Capture logs

bundle_id = mcp__XcodeBuildMCP__get_app_bundle_id()
log_handle = mcp__XcodeBuildMCP__start_sim_log_cap(bundle_id)

# Interact with app...

# mcp__XcodeBuildMCP__tap(id="loginButton")

# Phase 5: Stop and analyze

raw_log = mcp__XcodeBuildMCP__stop_sim_log_cap(log_handle)
errors = [line for line in raw_log.splitlines() if "error" in line.lower()]
print("\n".join(errors))

Key XcodeBuildMCP Functions for Log Analysis

The iOS Debugger Agent exposes these MCP functions for simulator interaction:

• mcp__XcodeBuildMCP__list_sims – Returns JSON array of all simulators with udid, state, and runtime properties
• mcp__XcodeBuildMCP__session_set_defaults – Configures project path, scheme, and simulator parameters
• mcp__XcodeBuildMCP__get_app_bundle_id – Retrieves the bundle identifier for the currently targeted app
• mcp__XcodeBuildMCP__start_sim_log_cap – Initiates streaming log capture for a specific bundle ID
• mcp__XcodeBuildMCP__stop_sim_log_cap – Terminates stream and returns captured log text
• mcp__XcodeBuildMCP__build_run_sim – Optional build and launch command for the configured scheme
• mcp__XcodeBuildMCP__describe_ui – Verifies app state by returning current UI hierarchy

Filtering and Analyzing Captured Logs

Once you retrieve the raw log string from stop_sim_log_cap, apply standard text processing to isolate specific events.

Filter for Errors and Warnings

Parse the log output to extract lines containing error indicators:

errors = [l for l in raw_log.splitlines() if "error" in l.lower()]
warnings = [l for l in raw_log.splitlines() if "warning" in l.lower()]

Detect Crashes and Exceptions

Search for crash signatures or exception patterns to identify fatal errors:

crashes = [l for l in raw_log.splitlines() if "crash" in l.lower()]
exceptions = [l for l in raw_log.splitlines() if "exception" in l.lower()]

Because the MCP calls operate as pure-function descriptors within the repository's permission model, the analysis logic executes safely on any macOS host without requiring custom shell scripts or external tooling dependencies.

Summary

• The iOS Debugger Agent in ios-debugger-agent/SKILL.md provides the orchestration logic for log capture
• Three-phase workflow: detect booted simulator with list_sims, configure session with session_set_defaults, capture logs with start_sim_log_cap and stop_sim_log_cap
• All MCP functions are pure-function descriptors that work within the repository's permission model
• Log analysis uses standard string operations after retrieving output from stop_sim_log_cap
• Source files include ios-debugger-agent/SKILL.md and ios-debugger-agent/agents/openai.yaml

Frequently Asked Questions

What is XcodeBuildMCP?

XcodeBuildMCP is a toolset that exposes Xcode build and simulator operations as Model Context Protocol (MCP) functions. According to the Dimillian/Skills source code, it provides declarative interfaces like mcp__XcodeBuildMCP__list_sims and mcp__XcodeBuildMCP__start_sim_log_cap that allow agents to interact with iOS simulators without executing arbitrary shell commands.

Do I need a physical device to capture logs?

No. The workflow specifically targets iOS simulators in a Booted state. The mcp__XcodeBuildMCP__list_sims function identifies available simulators, and the capture functions stream console logs from the simulator environment. Physical device provisioning is not required for this MCP-based approach.

How do I filter logs for specific keywords?

After calling mcp__XcodeBuildMCP__stop_sim_log_cap to retrieve the raw log text, use standard Python list comprehensions or string methods to filter. For example, [line for line in log.splitlines() if "crash" in line.lower()] isolates crash-related entries, while [line for line in log.splitlines() if "error" in line.lower()] extracts error messages.

Where is the orchestration logic stored?

The orchestration logic resides in ios-debugger-agent/SKILL.md within the Dimillian/Skills repository. This file defines the procedural workflow for the iOS Debugger Agent, including the sequence of MCP calls required to configure sessions and capture logs. Agent metadata is stored in ios-debugger-agent/agents/openai.yaml.

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