Xcode

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)

Use the included setup script which automates the installation and configuration process:

chmod +x setup.sh\n\n# Run the setup script
./setup.sh

Option 2: Manual Setup

When to Use 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

Follow these steps for manual installation:

1. Clone the repository:

git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

2. Verify prerequisites (these must be installed):

• Xcode and Xcode Command Line Tools
• Node.js v16 or higher
• npm
• Ruby (for CocoaPods support)
• CocoaPods (optional, for pod-related features)

3. Install dependencies:

npm install

4. Build the project:

npm run build

5. Create a configuration file:

cp .env.example .env\n\n# Option B: Create a minimal configuration
echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
echo "DEBUG=false" >> .env

6. For Claude Desktop integration (optional):

• Edit or create ~/Library/Application Support/Claude/claude_desktop_config.json
• Add the following configuration (adjust paths as needed):

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/xcode-mcp-server/dist/index.js"]
    }
  }
}

Usage# Starting the Server

npm start

For development mode with automatic restarts:

npm run dev

Connecting to AI Assistants

The server implements the Model Context Protocol (MCP), making it compatible with various AI assistants that support this protocol. To connect:

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

For a comprehensive overview of all available tools and their usage, see Tools Overview. For detailed usage examples and best practices, see User Guide.