The Xcode MCP Server enables AI assistants to interact with Xcode projects and related tools on macOS. It provides:
Project Management: Set base directory, specify project paths, retrieve active project information, create new projects, parse workspaces, and list schemes.
File Operations: Read, write, search, list, and create files and directories within projects.
Build and Testing: Build projects with specified schemes and configurations, run tests with optional test plans, analyze, clean, and archive projects.
Source Analysis: Analyze source files for issues and provide suggestions.
Dependency Management: Integrate with CocoaPods and Swift Package Manager.
Simulator Control: List, boot/shutdown iOS Simulators, install/launch apps, capture screenshots and recordings.
Xcode Utilities: Access
xcrun
functionality for compiling assets, generating icons, tracing performance, and managing Xcode versions.
Xcode MCP Server
An MCP (Model Context Protocol) server providing comprehensive Xcode integration for AI assistants. This server enables AI agents to interact with Xcode projects, manage iOS simulators, and perform various Xcode-related tasks with enhanced error handling and support for multiple project types.
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:
What the Setup Script Does:
Environment Verification:
Checks that you're running on macOS
Verifies Xcode is installed and accessible
Confirms Node.js (v16+) and npm are available
Checks for Ruby installation
Verifies CocoaPods installation (offers to install if missing)
Dependency Installation:
Runs
npm install
to install all required Node.js packagesExecutes
npm run build
to compile the TypeScript code
Configuration Setup:
Creates a
.env
file if one doesn't existPrompts for your projects base directory
Asks if you want to enable debug logging
Saves your configuration preferences
Claude Desktop Integration (Optional):
Offers to configure the server for Claude Desktop
Creates or updates the Claude Desktop configuration file
Sets up the proper command and arguments to launch the server
When to Use the Setup Script:
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
The script will guide you through the configuration process with clear prompts and helpful feedback.
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:
Clone the repository:
git clone https://github.com/r-huijts/xcode-mcp-server.git cd xcode-mcp-serverVerify 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)
Install dependencies:
npm installBuild the project:
npm run buildCreate a configuration file:
# Option A: Start with the example configuration cp .env.example .env # Option B: Create a minimal configuration echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env echo "DEBUG=false" >> .envEdit the
.env
file to set your preferred configuration.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"] } } }
Setup Troubleshooting
Common Setup Issues:
Build Errors:
Ensure you have the correct Node.js version (v16+)
Try deleting
node_modules
and runningnpm install
againCheck for TypeScript errors with
npx tsc --noEmit
Make sure all imports in the code are properly resolved
Missing Dependencies:
If you see errors about missing modules, run
npm install
againFor native dependencies, you may need Xcode Command Line Tools:
xcode-select --install
Permission Issues:
Ensure you have write permissions to the installation directory
For CocoaPods installation, you may need to use
sudo gem install cocoapods
Configuration Problems:
Verify your
.env
file has the correct format and valid pathsMake sure
PROJECTS_BASE_DIR
points to an existing directoryCheck that the path doesn't contain special characters that need escaping
Claude Desktop Integration:
Ensure the path in the Claude configuration points to the correct location of
index.js
Restart Claude Desktop after making configuration changes
Check that the server is running before attempting to use it with Claude
Usage
Starting the Server
For development mode with automatic restarts:
Configuration Options
You can configure the server in two ways:
Environment variables in
.env
file:PROJECTS_BASE_DIR=/path/to/your/projects DEBUG=true ALLOWED_PATHS=/path/to/additional/allowed/directory PORT=8080Command line arguments:
npm start -- --projects-dir=/path/to/your/projects --port=8080
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
The server implements the Model Context Protocol (MCP), making it compatible with various AI assistants that support this protocol. To connect:
Start the Xcode MCP server
Configure your AI assistant to use the server URL (typically
http://localhost:3000
)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.
Common Workflows
Setting Up a New Project
Working with Files
Building and Testing
Project Structure
How It Works
The Xcode MCP server uses the Model Context Protocol to provide a standardized interface for AI models to interact with Xcode projects. The server architecture is designed with several key components:
Core Components
Server Implementation: The main MCP server that handles tool registration and request processing.
Path Management: Ensures secure file access by validating all paths against allowed directories.
Project Management: Detects, loads, and manages different types of Xcode projects:
Standard Xcode projects (.xcodeproj)
Xcode workspaces (.xcworkspace)
Swift Package Manager projects (Package.swift)
Directory State: Maintains the active directory context for relative path resolution.
Tool Registry: Organizes tools into logical categories for different Xcode operations.
Request Flow
An AI assistant sends a tool execution request to the MCP server.
The server validates the request parameters and permissions.
The appropriate tool handler is invoked with the validated parameters.
The tool executes the requested operation, often using native Xcode commands.
Results are formatted and returned to the AI assistant.
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
The server intelligently handles different project types:
Standard Projects: Direct .xcodeproj manipulation
Workspaces: Manages multiple projects within a workspace
SPM Projects: Handles Swift Package Manager specific operations
This architecture allows AI assistants to seamlessly work with any type of Xcode project while maintaining security and providing detailed feedback.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add some amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)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
To add a new tool to the server:
Identify the appropriate category in the
src/tools/
directoryImplement the tool using the existing patterns with Zod schema validation
Register the tool in the category's
index.ts
fileAdd error handling with specific error messages
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
Start the server with debug logging enabled:
npm start -- --debug
Check the console output for detailed error messages
Examine the server logs for request and response details
For tool-specific issues, try running the equivalent Xcode command directly in the terminal
License
This project is licensed under the MIT License - see the LICENSE file for details.
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
local-only server
The server can only run on the client's local machine because it depends on local resources.
Bridges Claude AI with Xcode, enabling AI-powered code assistance, project management, and automated development tasks securely on your local machine.
- Features
- Installation
- Usage
- Project Structure
- How It Works
- Contributing
- Troubleshooting
- License
- Acknowledgments
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityA macOS-native bridge server that enables communication between different AI clients like Claude and Cline, allowing them to interact with each other through the Model Context Protocol.Last updated -23
- -securityAlicense-qualityA server that acts as a bridge between Claude and local Xcode projects, enabling AI-powered code assistance, project management, and automated development tasks without exposing your code to the internet.Last updated -MIT License
- AsecurityAlicenseAqualityConnects Blender to Claude AI through the Model Context Protocol, enabling AI-assisted 3D modeling, scene creation, and manipulation through natural language commands.Last updated -17MIT License
- -security-license-qualityEnables AI assistants like Claude to interact with Autodesk Construction Cloud Build platform for construction project management, including issues tracking, RFIs, submittals, and document management through natural language.Last updated -