Stefan-Nitu/mcp-xcode-server

MCP Xcode Server

A Model Context Protocol (MCP) server that enables AI assistants to build, test, run, and manage Apple platform projects through natural language interactions.

Version: 0.6.0

Purpose

This MCP server bridges the gap between AI assistants and Apple's development ecosystem. It allows AI tools like Claude to directly execute Xcode and Swift Package Manager commands, enabling automated development workflows without manual intervention. The server is designed for token efficiency, providing concise output while maintaining comprehensive error reporting and debugging capabilities.

Why Use MCP Xcode Server?

Key Advantages

• AI-Native Development: Enables AI assistants to build, test, and run iOS/macOS apps directly
• Token Efficiency: Optimized output shows only essential information (errors, warnings, test results)
• Smart Error Handling: Parses build errors and provides actionable suggestions
• Visual Debugging: Capture simulator screenshots to verify UI changes
• Automatic Simulator Management: Intelligently reuses running simulators to save time
• Xcode Integration: Auto-syncs file operations with Xcode projects via hooks
• Persistent Logging: All operations saved to ~/.mcp-xcode-server/logs/ for debugging
• Multi-Platform: Supports iOS, macOS, tvOS, watchOS, and visionOS from a single interface

Use Cases

• Automated Testing: AI can run your test suites and analyze failures
• Build Verification: Quickly verify code changes compile across platforms
• UI Development: Build and screenshot apps to verify visual changes
• Dependency Management: Add, update, or remove Swift packages programmatically
• Cross-Platform Development: Test the same code on multiple Apple platforms
• CI/CD Integration: Automate build and test workflows through natural language

Limitations

What It Can't Do

• No SwiftUI Previews: Xcode's live preview requires the full IDE
• No Interactive UI Testing: Cannot simulate user interactions (taps, swipes)
• No Physical Devices: Simulator-only for iOS/tvOS/watchOS/visionOS
• No Debugging: No breakpoints, step-through debugging, or LLDB access
• No Xcode UI Features: Project configuration, storyboard editing require Xcode
• Platform Requirements: Requires macOS 14+, Xcode 16+, iOS 17+ simulators

When You Still Need Xcode

• Designing UI with Interface Builder or SwiftUI previews
• Debugging with breakpoints and variable inspection
• Profiling with Instruments
• Managing certificates and provisioning profiles
• Testing on physical devices
• Using Xcode-specific features (Playgrounds, AR tools, etc.)

Core Features

Build & Test Automation

• Build and run Xcode projects/workspaces
• Execute Swift Package Manager packages
• Run XCTest and Swift Testing suites
• Xcode projects: Support for custom build configurations (Debug, Release, Beta, Staging, etc.)
• Swift packages: Standard SPM configurations (Debug/Release only - SPM limitation)

Simulator Management

• List and boot simulators for any Apple platform
• Capture screenshots for visual verification
• Install/uninstall apps
• Retrieve device logs with filtering

Error Intelligence

• Compile Errors: Shows file, line, column with error message
• Scheme Errors: Suggests using list_schemes tool
• Code Signing: Identifies certificate and provisioning issues
• Dependencies: Detects missing modules and version conflicts

File Sync Hooks

• Automatically syncs file operations with Xcode projects
• Intelligently assigns files to correct build phases (Sources, Resources, etc.)
• Respects .no-xcode-sync opt-out files
• Maintains proper group structure in Xcode

Installation

Prerequisites

• macOS 14.0 or later
• Xcode 16.0 or later
• Node.js 18+
• Xcode Command Line Tools
• Simulators for target platforms

Quick Setup

# Install globally
npm install -g mcp-xcode-server

# Run interactive setup
mcp-xcode-server setup

The setup wizard will:

• Configure the MCP server for Claude
• Optionally set up Xcode sync hooks
• Build necessary helper tools

Manual Configuration

Add to ~/.claude.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "mcp-xcode-server": {
      "type": "stdio",
      "command": "mcp-xcode-server",
      "args": ["serve"],
      "env": {}
    }
  }
}

Available Tools

Building

• build_xcode: Build Xcode projects/workspaces (supports custom configurations)
• build_swift_package: Build Swift packages (Debug/Release only per SPM spec)
• run_xcode: Build and run on simulator/macOS
• run_swift_package: Execute Swift package executables

Testing

• test_xcode: Run XCTest/Swift Testing suites
• test_swift_package: Test Swift packages
• Supports test filtering by class/method

Project Information

• list_schemes: Get available Xcode schemes
• get_project_info: Comprehensive project details
• list_targets: List all build targets
• get_build_settings: Get scheme configuration

Simulator Management

• list_simulators: Show available devices
• boot_simulator: Start a simulator
• shutdown_simulator: Stop a simulator
• view_simulator_screen: Capture screenshot

App Management

• install_app: Install app on simulator
• uninstall_app: Remove app by bundle ID
• get_device_logs: Retrieve filtered device logs

Distribution

• archive_project: Create .xcarchive
• export_ipa: Export IPA from archive

Maintenance

• clean_build: Clean build artifacts/DerivedData
• manage_dependencies: Add/remove/update Swift packages

Platform Support

Architecture

The server follows Clean/Hexagonal Architecture with SOLID principles:

Core Structure

src/
├── features/         # Feature-based vertical slices
│   ├── build/       # Build feature
│   │   ├── domain/  # Build domain objects
│   │   ├── use-cases/
│   │   ├── infrastructure/
│   │   ├── controllers/
│   │   └── factories/
│   ├── simulator/   # Simulator management
│   │   └── ...same structure...
│   └── app-management/ # App installation
│       └── ...same structure...
├── shared/          # Cross-feature shared code
│   ├── domain/      # Shared value objects
│   └── infrastructure/
├── application/     # Application layer ports
│   └── ports/       # Interface definitions
├── presentation/    # MCP presentation layer
│   ├── interfaces/  # MCP contracts
│   └── formatters/  # Output formatting
└── infrastructure/  # Shared infrastructure
    ├── repositories/
    └── services/

Key Design Principles

• Clean Architecture: Dependency rule - inner layers know nothing about outer layers
• Domain-Driven Design: Rich domain models with embedded validation
• Type Safety: Full TypeScript with domain primitives and parse-don't-validate pattern
• Security First: Path validation, command injection protection at boundaries
• Error Recovery: Typed domain errors with graceful handling and helpful suggestions

Logging

All operations are logged to ~/.mcp-xcode-server/logs/:

• Daily folders (e.g., 2025-01-27/)
• 7-day automatic retention
• Full xcodebuild/swift output preserved
• Symlinks to latest logs for easy access

Development

# Build
npm run build

# Test
npm test              # All tests
npm run test:unit    # Unit tests only
npm run test:e2e     # End-to-end tests
npm run test:coverage # With coverage

# Development
npm run dev          # Build and run

Contributing

Contributions welcome! Please ensure:

• Tests pass (npm test)
• Code follows SOLID principles
• New tools include tests
• Documentation updated

License

MIT

Support

• Report issues: GitHub Issues
• Documentation: MCP Protocol