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:

2. Run directly with uvx:

uvx xctools-mcp-server

Method 2: Local Development Installation

1. Prerequisites:

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"

2. "No developer directory found"

3. Permission errors

4. Tool not found errors

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