Xcode Instruments CLI

Name: Xcode Instruments CLI
Author: nzrsky

@nzrsky

Repository

About Xcode Instruments CLI

No overview available yet

#xcode #instruments #xctrace #xcrun #xcodebuild

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "xcinstruments": {
      "command": "uvx",
      "args": [
        "xctools-mcp-server"
      ],
      "env": {}
    }
  }
}

Tools

Find the path to a development tool using xcrun. Args: tool_name: Name of the tool to find (e.g., 'clang', 'swift', 'texturetool') sdk: SDK name to search in (e.g., 'iphoneos', 'macosx') Returns: Absolute path to the tool

Show the path to the SDK. Args: sdk: SDK name (e.g., 'iphoneos', 'macosx'). Uses default if not specified. Returns: Path to the SDK

Show the version of the SDK. Args: sdk: SDK name (e.g., 'iphoneos', 'macosx'). Uses default if not specified. Returns: Version of the SDK

Run a development tool via xcrun. Args: tool_name: Name of the tool to run args: Arguments to pass to the tool sdk: SDK to use when running the tool verbose: Enable verbose output Returns: Output from the tool

Build an Xcode project or workspace. Args: project: Path to .xcodeproj file workspace: Path to .xcworkspace file scheme: Scheme name to build target: Target name to build configuration: Build configuration (Debug, Release, etc.) sdk: SDK to build against destination: Destination to build for clean: Whether to clean before building Returns: Build output

Run tests for an Xcode project or workspace. Args: project: Path to .xcodeproj file workspace: Path to .xcworkspace file scheme: Scheme name to test (required) destination: Destination to test on test_plan: Name of test plan to use only_testing: List of test identifiers to run exclusively skip_testing: List of test identifiers to skip Returns: Test results

Archive an Xcode project or workspace. Args: project: Path to .xcodeproj file workspace: Path to .xcworkspace file scheme: Scheme name to archive (required) archive_path: Path where to save the archive Returns: Archive result

List targets and configurations in a project, or schemes in a workspace. Args: project: Path to .xcodeproj file workspace: Path to .xcworkspace file Returns: List of targets/schemes and configurations

List all available SDKs. Returns: List of available SDKs

List valid destinations for a project or workspace and scheme. Args: project: Path to .xcodeproj file workspace: Path to .xcworkspace file scheme: Scheme name (required) Returns: List of valid destinations

Record a new Instruments trace using the specified template. Args: template: Template name or path to use for recording output_path: Path to save the trace file device: Device name or UDID to record on time_limit: Time limit for recording (e.g., '5s', '1m') all_processes: Record all processes on the system attach_process: Process name or PID to attach to launch_command: Command and arguments to launch and record Returns: Recording result

Import a supported file format into an Instruments trace file. Args: input_file: Path to the input file to import (e.g., .logarchive, .ktrace) template: Template name or path to use for import output_path: Path to save the imported trace file instrument: Name of instrument to add to import configuration package: Path to Instruments Package to install temporarily Returns: Import result

Export data from an Instruments trace file. Args: input_file: Path to the .trace file to export from output_path: Path to save the exported data toc: Export table of contents xpath: XPath expression to select specific data Returns: Exported data or success message

List available devices, templates, or instruments. Args: list_type: What to list ('devices', 'templates', 'instruments') Returns: List of requested items

Symbolicate a trace file using debug symbols. Args: input_file: Path to the .trace file to symbolicate output_path: Path to save the symbolicated trace dsym_path: Path to dSYM file or directory containing dSYMs Returns: Symbolication result

Overview

What is Xcode Instruments CLI?

A Model Context Protocol (MCP) server that provides structured access to Xcode development tools including xcrun, xcodebuild, and xctrace. It is designed for developers working with Xcode projects who want to manage builds, tests, archives, and performance traces through an MCP-compatible client such as Claude Desktop or VS Code.

How to use Xcode Instruments CLI?

Install with uvx xctools-mcp-server (requires Python 3.13+, Xcode Command Line Tools, and uv) or clone the repo and run pip install . then xctools-mcp-server. Configure by adding the server definition to your MCP client's configuration file (e.g., claude_desktop_config.json or VS Code settings.json) using either the installed command or uvx.

Key features of Xcode Instruments CLI

Complete Xcode toolchain access through xcrun
Project building and testing with xcodebuild
Performance analysis using xctrace (Instruments)
SDK and destination management
Comprehensive error handling with detailed messages
Cross-platform compatibility (macOS with Xcode installed)

Use cases of Xcode Instruments CLI

Find the path to development tools like clang or swift
Build, test, and archive Xcode projects or workspaces
Record, import, export, and symbolicate Instruments traces
List available SDKs, build destinations, devices, and templates

FAQ from Xcode Instruments CLI

What are the runtime requirements for Xcode Instruments CLI?

macOS (required), Xcode Command Line Tools or full Xcode installation, Python 3.13 or higher, and an MCP-compatible client such as Claude Desktop or VS Code with the MCP extension.

How do I install Xcode Instruments CLI?

You can run it directly with uvx xctools-mcp-server or install locally by cloning the repository and running pip install . inside the cloned directory.

What Xcode tools does Xcode Instruments CLI expose?

It provides tools for xcrun (find tool, show SDK path/version, run tool), xcodebuild (build, test, archive, list, show SDKs/destinations), and xctrace (record, import, export, list, symbolicate).

What should I do if I get a “xcrun: error: unable to find utility” message?

Ensure Xcode Command Line Tools are installed via xcode-select --install and verify the configured developer directory with xcode-select -p.

Does the server access my file system beyond Xcode tools?

The README states that security considerations cover read and simulator management operations only, with no host file system access beyond specified app paths and push notification payloads validated for structure.