Xcode MCP Server

Features

Project Management

• Set active projects and get detailed project information

• Create new Xcode projects from templates (iOS, macOS, watchOS, tvOS)

• Add files to Xcode projects with target and group specification

• Parse workspace documents to find associated projects

• List available schemes in projects and workspaces

File Operations

• Read/write files with support for different encodings

• Handle binary files with base64 encoding/decoding

• Search for text content within files using patterns and regex

• Check file existence and get file metadata

• Create directory structures automatically

Build & Testing

• Build projects with customizable options

• Run tests with detailed failure reporting

• Analyze code for potential issues

• Clean build directories

• Archive projects for distribution

CocoaPods Integration

• Initialize CocoaPods in projects

• Install and update pods

• Add and remove pod dependencies

• Execute arbitrary pod commands

Swift Package Manager

• Initialize new Swift packages

• Add and remove package dependencies with various version requirements

• Update packages and resolve dependencies

• Generate documentation for Swift packages using DocC

• Run tests and build Swift packages

iOS Simulator Tools

• List available simulators with detailed information

• Boot and shut down simulators

• Install and launch apps on simulators

• Take screenshots and record videos

• Manage simulator settings and state

Xcode Utilities

• Execute Xcode commands via xcrun

• Compile asset catalogs

• Generate app icon sets from source images

• Trace app performance

• Export and validate archives for App Store submission

• Switch between different Xcode versions

Installation

Prerequisites

• macOS with Xcode 14.0 or higher installed

• Node.js 16 or higher

• npm or yarn

• Swift 5.5+ for Swift Package Manager features

• CocoaPods (optional, for CocoaPods integration)

Setup

Option 1: Automated Setup (Recommended)

1. Environment Verification:

2. Dependency Installation:

3. Configuration Setup:

4. Claude Desktop Integration (Optional):

• First-time installation to ensure all prerequisites are met

• When you want guided configuration with interactive prompts

• If you want to quickly set up Claude Desktop integration

• To verify your environment has all necessary components

Option 2: Manual Setup

• You prefer explicit control over each installation step

• You have a custom environment or non-standard configuration

• You're setting up in a CI/CD pipeline or automated environment

• You want to customize specific aspects of the installation process

• You're an experienced developer familiar with Node.js projects

1. Clone the repository:

2. Verify prerequisites (these must be installed):

3. Install dependencies:

4. Build the project:

5. Create a configuration file:Edit the .env file to set your preferred configuration.

6. For Claude Desktop integration (optional):

Setup Troubleshooting

1. Build Errors:

2. Missing Dependencies:

3. Permission Issues:

4. Configuration Problems:

5. Claude Desktop Integration:

Usage

Starting the Server

Configuration Options

1. Environment variables in .env file:

2. Command line arguments:

Key Configuration Parameters

• PROJECTS_BASE_DIR / --projects-dir: Base directory for projects (required)

• ALLOWED_PATHS / --allowed-paths: Additional directories to allow access to (comma-separated)

• PORT / --port: Port to run the server on (default: 3000)

• DEBUG / --debug: Enable debug logging (default: false)

• LOG_LEVEL / --log-level: Set logging level (default: info)

Connecting to AI Assistants

1. Start the Xcode MCP server

2. Configure your AI assistant to use the server URL (typically http://localhost:3000)

3. The AI assistant will now have access to all the Xcode tools provided by the server

Tool Documentation

Common Workflows

Setting Up a New Project

Working with Files

Building and Testing

Project Structure

How It Works

Core Components

1. Server Implementation: The main MCP server that handles tool registration and request processing.

2. Path Management: Ensures secure file access by validating all paths against allowed directories.

3. Project Management: Detects, loads, and manages different types of Xcode projects:

4. Directory State: Maintains the active directory context for relative path resolution.

5. Tool Registry: Organizes tools into logical categories for different Xcode operations.

Request Flow

1. An AI assistant sends a tool execution request to the MCP server.

2. The server validates the request parameters and permissions.

3. The appropriate tool handler is invoked with the validated parameters.

4. The tool executes the requested operation, often using native Xcode commands.

5. Results are formatted and returned to the AI assistant.

6. Comprehensive error handling provides meaningful feedback for troubleshooting.

Safety Features

• Path Validation: All file operations are restricted to allowed directories.

• Error Handling: Detailed error messages help diagnose issues.

• Parameter Validation: Input parameters are validated using Zod schemas.

• Process Management: External processes are executed safely with proper error handling.

Project Type Support

• Standard Projects: Direct .xcodeproj manipulation

• Workspaces: Manages multiple projects within a workspace

• SPM Projects: Handles Swift Package Manager specific operations

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Guidelines

• Follow the existing code style and organization

• Add comprehensive error handling with specific error messages

• Write tests for new functionality

• Update documentation to reflect your changes

• Ensure compatibility with different project types (standard, workspace, SPM)

Adding New Tools

1. Identify the appropriate category in the src/tools/ directory

2. Implement the tool using the existing patterns with Zod schema validation

3. Register the tool in the category's index.ts file

4. Add error handling with specific error messages

5. Document the tool in the appropriate documentation files

Troubleshooting

Common Issues

• Path Access Errors: Ensure the paths you're trying to access are within the allowed directories

• Build Failures: Check that Xcode command line tools are installed and up to date

• Tool Not Found: Verify that the tool name is correct and properly registered

• Parameter Validation Errors: Check the parameter types and requirements in the tool documentation

Debugging

1. Start the server with debug logging enabled: npm start -- --debug

2. Check the console output for detailed error messages

3. Examine the server logs for request and response details

4. For tool-specific issues, try running the equivalent Xcode command directly in the terminal

License

Acknowledgments

• Thanks to the Model Context Protocol team for the MCP SDK

• Built with TypeScript and Node.js

• Uses Xcode command line tools and Swift Package Manager

• Special thanks to all contributors who have helped improve the server's functionality and robustness

Xcode MCP Server

Features

Project Management

• Set active projects and get detailed project information

• Create new Xcode projects from templates (iOS, macOS, watchOS, tvOS)

• Add files to Xcode projects with target and group specification

• Parse workspace documents to find associated projects

• List available schemes in projects and workspaces

File Operations

• Read/write files with support for different encodings

• Handle binary files with base64 encoding/decoding

• Search for text content within files using patterns and regex

• Check file existence and get file metadata

• Create directory structures automatically

Build & Testing

• Build projects with customizable options

• Run tests with detailed failure reporting

• Analyze code for potential issues

• Clean build directories

• Archive projects for distribution

CocoaPods Integration

• Initialize CocoaPods in projects

• Install and update pods

• Add and remove pod dependencies

• Execute arbitrary pod commands

Swift Package Manager

• Initialize new Swift packages

• Add and remove package dependencies with various version requirements

• Update packages and resolve dependencies

• Generate documentation for Swift packages using DocC

• Run tests and build Swift packages

iOS Simulator Tools

• List available simulators with detailed information

• Boot and shut down simulators

• Install and launch apps on simulators

• Take screenshots and record videos

• Manage simulator settings and state

Xcode Utilities

• Execute Xcode commands via xcrun

• Compile asset catalogs

• Generate app icon sets from source images

• Trace app performance

• Export and validate archives for App Store submission

• Switch between different Xcode versions

Installation

Prerequisites

• macOS with Xcode 14.0 or higher installed

• Node.js 16 or higher

• npm or yarn

• Swift 5.5+ for Swift Package Manager features

• CocoaPods (optional, for CocoaPods integration)

Setup

Option 1: Automated Setup (Recommended)

1. Environment Verification:

2. Dependency Installation:

3. Configuration Setup:

4. Claude Desktop Integration (Optional):

• First-time installation to ensure all prerequisites are met

• When you want guided configuration with interactive prompts

• If you want to quickly set up Claude Desktop integration

• To verify your environment has all necessary components

Option 2: Manual Setup

• You prefer explicit control over each installation step

• You have a custom environment or non-standard configuration

• You're setting up in a CI/CD pipeline or automated environment

• You want to customize specific aspects of the installation process

• You're an experienced developer familiar with Node.js projects

1. Clone the repository:

2. Verify prerequisites (these must be installed):

3. Install dependencies:

4. Build the project:

5. Create a configuration file:Edit the .env file to set your preferred configuration.

6. For Claude Desktop integration (optional):

Setup Troubleshooting

1. Build Errors:

2. Missing Dependencies:

3. Permission Issues:

4. Configuration Problems:

5. Claude Desktop Integration:

Usage

Starting the Server

Configuration Options

1. Environment variables in .env file:

2. Command line arguments:

Key Configuration Parameters

• PROJECTS_BASE_DIR / --projects-dir: Base directory for projects (required)

• ALLOWED_PATHS / --allowed-paths: Additional directories to allow access to (comma-separated)

• PORT / --port: Port to run the server on (default: 3000)

• DEBUG / --debug: Enable debug logging (default: false)

• LOG_LEVEL / --log-level: Set logging level (default: info)

Connecting to AI Assistants

1. Start the Xcode MCP server

2. Configure your AI assistant to use the server URL (typically http://localhost:3000)

3. The AI assistant will now have access to all the Xcode tools provided by the server

Tool Documentation

Common Workflows

Setting Up a New Project

Working with Files

Building and Testing

Project Structure

How It Works

Core Components

1. Server Implementation: The main MCP server that handles tool registration and request processing.

2. Path Management: Ensures secure file access by validating all paths against allowed directories.

3. Project Management: Detects, loads, and manages different types of Xcode projects:

4. Directory State: Maintains the active directory context for relative path resolution.

5. Tool Registry: Organizes tools into logical categories for different Xcode operations.

Request Flow

1. An AI assistant sends a tool execution request to the MCP server.

2. The server validates the request parameters and permissions.

3. The appropriate tool handler is invoked with the validated parameters.

4. The tool executes the requested operation, often using native Xcode commands.

5. Results are formatted and returned to the AI assistant.

6. Comprehensive error handling provides meaningful feedback for troubleshooting.

Safety Features

• Path Validation: All file operations are restricted to allowed directories.

• Error Handling: Detailed error messages help diagnose issues.

• Parameter Validation: Input parameters are validated using Zod schemas.

• Process Management: External processes are executed safely with proper error handling.

Project Type Support

• Standard Projects: Direct .xcodeproj manipulation

• Workspaces: Manages multiple projects within a workspace

• SPM Projects: Handles Swift Package Manager specific operations

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Guidelines

• Follow the existing code style and organization

• Add comprehensive error handling with specific error messages

• Write tests for new functionality

• Update documentation to reflect your changes

• Ensure compatibility with different project types (standard, workspace, SPM)

Adding New Tools

1. Identify the appropriate category in the src/tools/ directory

2. Implement the tool using the existing patterns with Zod schema validation

3. Register the tool in the category's index.ts file

4. Add error handling with specific error messages

5. Document the tool in the appropriate documentation files

Troubleshooting

Common Issues

• Path Access Errors: Ensure the paths you're trying to access are within the allowed directories

• Build Failures: Check that Xcode command line tools are installed and up to date

• Tool Not Found: Verify that the tool name is correct and properly registered

• Parameter Validation Errors: Check the parameter types and requirements in the tool documentation

Debugging

1. Start the server with debug logging enabled: npm start -- --debug

2. Check the console output for detailed error messages

3. Examine the server logs for request and response details

4. For tool-specific issues, try running the equivalent Xcode command directly in the terminal

License

Acknowledgments

• Thanks to the Model Context Protocol team for the MCP SDK

• Built with TypeScript and Node.js

• Uses Xcode command line tools and Swift Package Manager

• Special thanks to all contributors who have helped improve the server's functionality and robustness