Skip to main content
Glama

MCP Xcode

by Stefan-Nitu

MCP Xcode Server

CI

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

Platform

Simulator Required

Default Device

Min Version

iOS

Yes

iPhone 16 Pro

iOS 17+

macOS

No

Host machine

macOS 14+

tvOS

Yes

Apple TV

tvOS 17+

watchOS

Yes

Apple Watch Series 10

watchOS 10+

visionOS

Yes

Apple Vision Pro

visionOS 1.0+

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

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables AI assistants to build, test, run, and manage Apple platform projects (iOS, macOS, tvOS, watchOS, visionOS) directly through Xcode. Provides comprehensive control over Xcode projects, Swift packages, simulators, and development workflows without leaving your editor.

  1. Version: 0.6.0
    1. Purpose
      1. Why Use MCP Xcode Server?
        1. Key Advantages
        2. Use Cases
      2. Limitations
        1. What It Can't Do
        2. When You Still Need Xcode
      3. Core Features
        1. Build & Test Automation
        2. Simulator Management
        3. Error Intelligence
        4. File Sync Hooks
      4. Installation
        1. Prerequisites
        2. Quick Setup
        3. Manual Configuration
      5. Available Tools
        1. Building
        2. Testing
        3. Project Information
        4. Simulator Management
        5. App Management
        6. Distribution
        7. Maintenance
      6. Platform Support
        1. Architecture
          1. Core Structure
          2. Key Design Principles
        2. Logging
          1. Development
            1. Contributing
              1. License
                1. Support

                  Related MCP Servers

                  • -
                    security
                    A
                    license
                    -
                    quality
                    Provides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.
                    Last updated -
                    9
                    MIT License
                  • A
                    security
                    A
                    license
                    A
                    quality
                    Bridges Claude AI with Xcode, enabling AI-powered code assistance, project management, and automated development tasks securely on your local machine.
                    Last updated -
                    17
                    319
                    MIT License
                    • Apple
                  • A
                    security
                    F
                    license
                    A
                    quality
                    A Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.
                    Last updated -
                    18
                    17
                    47
                  • -
                    security
                    A
                    license
                    -
                    quality
                    Connects to Xcode's build system to extract, parse, and display errors and warnings from your Swift projects, helping AI assistants quickly identify code issues without manually searching through build logs.
                    Last updated -
                    5
                    MIT License
                    • Apple

                  View all related MCP servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/Stefan-Nitu/mcp-xcode'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server