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

Prerequisites:
- Python 3.13+
- Xcode with Command Line Tools installed
- uvx: curl -LsSf https://astral.sh/uv/install.sh | sh
Run directly with uvx:
```
uvx xctools-mcp-server
```

Method 2: Local Development Installation

Prerequisites:
- Python 3.13+
- Xcode with Command Line Tools installed

Clone and install:

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

Run the server:
```
xctools-mcp-server
```

Method 3: Build from Source

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

Install the MCP Extension from the VS Code marketplace
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": {}
    }
  }
}

Restart VS Code to load the MCP server
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

"xcrun: error: unable to find utility"
- Ensure Xcode Command Line Tools are installed: xcode-select --install
- Verify Xcode is properly configured: xcode-select -p
"No developer directory found"
- Install Xcode from the Mac App Store
- Accept Xcode license: sudo xcodebuild -license accept
Permission errors
- Ensure the user has necessary permissions to access Xcode tools
- Try running with proper macOS development permissions
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

xctools