Xcode Instruments CLI

XCTools MCP Server

A Model Context Protocol (MCP) server that provides structured access to Xcode development tools including xcrun, xcodebuild, and xctrace.

Installation

Method 1: Using uvx

1. Prerequisites:

   • Python 3.13+
   • Xcode with Command Line Tools installed
   • uvx: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Run directly with uvx:

   uvx xctools-mcp-server
   

Method 2: Local Development Installation

1. Prerequisites:

   • Python 3.13+
   • Xcode with Command Line Tools installed

2. Clone and install:

   git clone https://github.com/nzrsky/xctools-mcp-server
   cd xctools-mcp-server
   pip install .
   

3. Run the server:

   xctools-mcp-server
   

Method 3: Build from Source

1. Build the wheel:

   python -m build --wheel
   pip install dist/xctools_mcp_server-0.1.0-py3-none-any.whl
   

Configuration

For Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Or if using uvx:

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

For VS Code with MCP Extension

1. Install the MCP Extension from the VS Code marketplace
2. Add server configuration to your VS Code settings (settings.json):

{
  "mcp.servers": {
    "xctools": {
      "command": "xctools-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Or if using uvx:

{
  "mcp.servers": {
    "xctools": {
      "command": "uvx",
      "args": ["xctools-mcp-server"],
      "env": {}
    }
  }
}

3. Restart VS Code to load the MCP server
4. Use the Command Palette (Cmd+Shift+P) and search for "MCP" commands to interact with the Xcode development tools

For Other MCP Clients

The server runs on stdio, so you can invoke it directly:

With installed package:

xctools-mcp-server

With uvx:

uvx xctools-mcp-server

Features

• 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)

Available Tools

XCRUN Tools

• xcrun_find_tool - Find the path to development tools (clang, swift, etc.)
• xcrun_show_sdk_path - Show the path to SDKs
• xcrun_show_sdk_version - Show SDK versions
• xcrun_run_tool - Run any development tool via xcrun

XCODEBUILD Tools

• xcodebuild_build - Build Xcode projects or workspaces
• xcodebuild_test - Run tests for projects/workspaces
• xcodebuild_archive - Archive projects for distribution
• xcodebuild_list - List targets, schemes, and configurations
• xcodebuild_show_sdks - List all available SDKs
• xcodebuild_show_destinations - Show valid build destinations

XCTRACE Tools (Instruments)

• xctrace_record - Record new Instruments traces
• xctrace_import - Import supported files into trace format
• xctrace_export - Export data from trace files
• xctrace_list - List available devices, templates, or instruments
• xctrace_symbolicate - Symbolicate traces with debug symbols

Usage Examples

Finding Development Tools

# Find the path to a specific tool
"Find the path to clang compiler"

# Show SDK path for iOS
"Show the path to the iOS SDK"

# Get SDK version information
"Show the version of the iOS SDK"

Building Projects

# Build an Xcode project
"Build the project MyApp.xcodeproj for iOS simulator"

# Run tests for a workspace
"Run tests for MyApp.xcworkspace on iPhone 15 Pro simulator"

# Archive for distribution
"Archive MyApp.xcworkspace for release"

# List project information
"List all schemes and targets in MyApp.xcodeproj"

Performance Analysis with Instruments

# Record a trace for Time Profiler
"Record a Time Profiler trace for MyApp on iPhone 15 Pro for 30 seconds"

# List available instruments
"List all available Instruments templates"

# Export trace data
"Export data from trace file to XML format"

# Import a file for analysis
"Import a .dtps file into Instruments trace format"

SDK and Destination Management

# List all available SDKs
"Show all available SDKs for building"

# Show build destinations
"List all available destinations for iOS builds"

# Run a tool via xcrun
"Run swift command with version flag via xcrun"

Error Handling

The server includes comprehensive error handling:

• Command failures: Returns detailed error messages from xcrun, xcodebuild, and xctrace
• Missing Xcode: Detects when Xcode Command Line Tools are not available
• Invalid parameters: Validates tool arguments and provides helpful error messages
• Tool availability: Checks for required tools before execution

Troubleshooting

Common Issues

1. "xcrun: error: unable to find utility"

   • Ensure Xcode Command Line Tools are installed: xcode-select --install
   • Verify Xcode is properly configured: xcode-select -p

2. "No developer directory found"

   • Install Xcode from the Mac App Store
   • Accept Xcode license: sudo xcodebuild -license accept

3. Permission errors

   • Ensure the user has necessary permissions to access Xcode tools
   • Try running with proper macOS development permissions

4. Tool not found errors

   • Verify the specific tool is available in your Xcode installation
   • Some tools may require specific Xcode versions or additional components

Requirements

• macOS: Required (Xcode development tools are macOS-only)
• Xcode: Xcode Command Line Tools or full Xcode installation
• Python: 3.13 or higher
• MCP Client: Claude Desktop, VS Code with MCP extension, or any MCP-compatible client

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

• Invalid parameters: Validates input parameters before execution
• File operations: Handles temporary files for push notifications safely

Security Considerations

• The server only exposes read and simulator management operations
• No access to host file system beyond specified app paths
• Push notification payloads are validated for structure
• Privacy permission changes are explicit and logged

Development Notes

• Built specifically for iOS development workflows
• Optimized for common simulator management tasks
• Structured output parsing for JSON responses
• Support for both individual and batch operations
• Compatible with Xcode 15+ simulator features