DOCSEARCHbyAlgolia
Submit Docs

XcodeBuildMCP

repository·main·Indexed 27 days ago

https://github.com/getsentry/xcodebuildmcp

A Model Context Protocol (MCP) server and CLI (version 2.7.0) that provides AI agents with tools for Xcode project management, simulator management, and app utilities. It enables building and testing iOS and macOS projects via xcodebuild, featuring a Claude UI benchmark harness for auditing automation behavior and a CLI for direct terminal access to build tools.

Tokens
10.6K
Snippets
13
Records
69
Agent score
91%

What's inside xcodebuildmcp

  1. Use XcodeBuildMCP for iOS/macOS/watchOS/tvOS/visionOS development

    main

    XcodeBuildMCP provides a high-level toolset for mobile and desktop development, replacing raw xcodebuild, xcrun, or simctl commands. It supports building, testing, running, debugging, logging, and UI automation.

    Key Capabilities:

    • Session Management: Configure project, scheme, simulator, and device defaults to reduce repetitive parameters.
    • Project Discovery: Find Xcode projects/workspaces, list schemes, and inspect build settings.
    • Simulator Workflows: Build, run, test, install, and launch apps on iOS simulators; manage simulator state (boot, erase, location, appearance).
    • Device Workflows: Build, test, install, and launch apps on physical devices with code signing.
    • macOS Workflows: Build, run, and test macOS applications.
    • Log Capture: Stream and capture logs from simulators and devices.
    • LLDB Debugging: Attach debugger, set breakpoints, inspect stack traces/variables, and execute LLDB commands.
    • UI Automation: Capture screenshots, inspect view hierarchies, perform gestures (taps/swipes), type text, and press hardware buttons.
    • SwiftPM: Build, run, test, and manage Swift Package Manager projects.
    • Project Scaffolding: Generate new iOS/macOS project templates.

    Note: Only simulator workflow tools are enabled by default. To use device, macOS, debugging, or UI automation capabilities, you must configure them in .xcodebuildmcp/config.yaml.

  2. Capabilities of XcodeBuildMCP

    main

    The xcodebuildmcp CLI provides a high-level interface for Apple platform development (iOS, macOS, watchOS, tvOS, and visionOS), replacing raw commands like xcodebuild, xcrun, or simctl.

    Key capabilities include:

    • Simulator and device build, test, and run operations.
    • Debugging and log capture.
    • UI automation.
    • Project discovery and scaffolding.
    • Session defaults and workflow configuration.

  3. View aggregate benchmark summaries

    main

    When running the harness with the --all flag, an aggregate summary is appended to the end of the output. This summary provides a high-level overview of all suites in the run:

    • Suites: Total count, completed, and incomplete.
    • Duration: Total time and the slowest individual suite.
    • Artifacts: The base directory for all results.
    • Status List: A per-suite breakdown showing status, duration, and the sequence delta (formatted as N missing / K additional calls).

  4. Run Claude UI benchmarks

    main

    The Claude UI benchmark harness allows you to run Claude Code against configurable tool surfaces to audit UI automation behavior. You can run specific suites, all committed suites, or render existing results without rerunning the benchmark.

    To run a specific suite:

    1. Build the project: npm run build
    2. Run the suite using npx tsx or the bench:claude-ui shortcut.

    To run all committed suites: Use the --all flag to execute every committed suite YAML and any private local suites located in benchmarks/claude-ui/local/suites/.

    To render existing results: If you want to view a report without triggering a new Claude run, use the --from-result flag pointing to the artifact directory or the result.json file.

  5. Establish Session Context with XcodeBuildMCP

    main

    To ensure commands execute correctly, follow these steps to establish session context:

    1. Show Defaults: Call session_show_defaults before performing your first build, run, or test action in a session.
    2. Discover Projects: Use discover_projs only if session_show_defaults indicates that the project/workspace context is missing or incorrect.
    3. Avoid Speculation: Do not run discovery tools speculatively or in parallel with session_show_defaults.
    4. Optimize Simulator Runs: For simulator workflows, prefer using the combined build-and-run tool rather than calling separate build and run commands.
    5. Avoid Redundant Builds: Do not chain a build-only command followed by a build-and-run command unless explicitly requested.

  6. Enable additional workflows in XcodeBuildMCP

    main

    By default, only simulator workflow tools are enabled. If you need to use tools for physical devices, macOS, debugging, or UI automation, you must enable them via configuration.

    To enable workflows:

    1. Update the enabled workflows in the .xcodebuildmcp/config.yaml file.
    2. Ask the user to reload or restart the session to apply the changes and surface the new tools.

  7. Install XcodeBuildMCP Agent Skills

    main

    XcodeBuildMCP includes optional skills to prime agents with instructions on how to use the tools effectively:

    • MCP Skill: Primes the agent for using the MCP server's tools.
    • CLI Skill: Primes the agent for navigating the CLI.

    To install skills with a global binary, use xcodebuildmcp init. Alternatively, use npx for a direct installation without a global binary.

  8. Discover XcodeBuildMCP workflows and tools

    main

    Instead of memorizing tool lists, use the CLI's built-in help system to discover available workflows, tools, and their specific arguments.

    Use the following command patterns for discovery:

    • List all available workflows: xcodebuildmcp --help
    • List available tools: xcodebuildmcp tools
    • Discover arguments for a specific workflow: xcodebuildmcp <workflow> --help
    • Discover arguments for a specific tool within a workflow: xcodebuildmcp <workflow> <tool> --help
    xcodebuildmcp tools

  9. Run the Reminders UI benchmark

    main

    The Reminders UI benchmark is a task designed to test the capabilities of an agent using the XcodeBuild MCP. The task involves interacting with the Reminders app on a configured simulator to create, manage, and verify a specific set of reminders.

    Task Steps:

    1. Launch Reminders on the configured simulator.
    2. Create a new list named MCP Benchmark List.
    3. Add reminders: Add exactly these three reminders to the MCP Benchmark List:
      • Buy milk benchmark
      • File report benchmark
      • Call team benchmark
    4. Complete reminders: Mark exactly these two as complete:
      • Buy milk benchmark
      • Call team benchmark
    5. Verify state: Ensure File report benchmark remains incomplete.
    6. Final Verification: Observe the list to confirm exactly two completed reminders and one incomplete reminder exist.

    Verification Rules:

    • Do not edit, rename, delete, reorder, or clean up reminders or lists during verification.
    • Do not create additional reminders or lists.
    • Verification must be performed by reading the saved list state using UI snapshots (and a screenshot if necessary).

    Return a concise final summary of the created and observed state.

  12. Install XcodeBuildMCP

    main

    You can install XcodeBuildMCP using either Homebrew or npm. Both methods provide access to both the CLI and the MCP server.

    Option A: Homebrew

    Best for macOS users who prefer system-wide package management.

    Option B: npm

    Requires Node.js 18 or later.

    To verify your installation, run xcodebuildmcp --help.

    # Via Homebrew
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

# Via npm
npm install -g xcodebuildmcp@latest