Xcode Integration MCP Server

Developer ToolsTypeScript

Interact with Xcode projects, manage iOS simulators, and perform Xcode-related tasks

Available Tools

set_active_project

Set the active Xcode project for subsequent operations

projectPathisWorkspace

get_project_info

Get detailed information about the current Xcode project

create_project

Create a new Xcode project from a template

nametemplatepathorganizationNameorganizationIdentifier

add_file

Add a file to the Xcode project

filePathtargetNamegroupPath

list_available_schemes

List all available schemes in the current project

read_file

Read the contents of a file

filePathencoding

write_file

Write content to a file

filePathcontentencoding

search_in_file

Search for text content within files

filePathpatternuseRegex

build_project

Build the current Xcode project

schemeconfigurationdestination

run_tests

Run tests for the current Xcode project

schemedestinationtestPlan

analyze_code

Analyze code for potential issues

schemeconfiguration

clean_build

Clean build directories

scheme

archive_project

Archive the project for distribution

schemeconfigurationarchivePath

pod_init

Initialize CocoaPods in the project

pod_install

Install CocoaPods dependencies

updateRepos

pod_add

Add a pod dependency

podNameversion

pod_remove

Remove a pod dependency

podName

swift_package_init

Initialize a new Swift package

nametype

swift_package_add_dependency

Add a dependency to a Swift package

urlversion

swift_package_build

Build a Swift package

configuration

The Xcode Integration MCP provides a comprehensive bridge between AI assistants and Apple's Xcode development environment. It enables AI agents to manage iOS, macOS, watchOS, and tvOS projects, perform build operations, run tests, and interact with CocoaPods and Swift Package Manager. With enhanced error handling and support for multiple project types, this MCP significantly improves the ability of AI assistants to help with iOS and macOS development tasks.

Overview

The Xcode Integration MCP server provides AI assistants with the ability to interact with Xcode projects, manage iOS simulators, and perform various Xcode-related tasks. This server bridges the gap between AI capabilities and iOS/macOS development workflows.

Installation

Prerequisites

macOS operating system
Xcode installed (latest version recommended)
Node.js and npm installed
CocoaPods (optional, for pod-related functionality)

Setup Instructions

Clone the repository:

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

Install dependencies:
```
npm install
```
Create a .env file based on the example:
```
cp .env.example .env
```
Run the setup script to configure the server:
```
./setup.sh
```
Build the server:
```
npm run build
```
Start the server:
```
npm start
```

Automatic Setup

The included setup.sh script automates the installation process by:

Checking for required dependencies (Node.js, Xcode)
Installing necessary npm packages
Setting up environment variables
Building the TypeScript code
Configuring the server for first use

If you encounter issues with the automatic setup, you can perform the steps manually as outlined above.

Configuration

The server can be configured through environment variables in the .env file:

PORT: The port on which the MCP server will run (default: 3000)
LOG_LEVEL: Logging verbosity (options: debug, info, warn, error)
DEFAULT_PROJECT_PATH: Default directory to look for Xcode projects
XCODE_PATH: Custom path to Xcode.app if not in the standard location

Usage

Once the server is running, AI assistants can interact with it through the Model Context Protocol. The server provides tools for:

Project Management

Setting active projects
Creating new Xcode projects from templates
Adding files to projects
Parsing workspace documents
Listing available schemes

File Operations

Reading and writing files
Handling binary files
Searching for text content
Managing file metadata

Build & Testing

Building projects
Running tests
Analyzing code
Cleaning build directories
Archiving projects

CocoaPods Integration

Initializing CocoaPods
Installing and updating pods
Managing pod dependencies

Swift Package Manager

Initializing Swift packages
Adding package dependencies
Building and testing packages

Troubleshooting

Common Issues

Server fails to start
- Ensure Xcode is properly installed and that you've accepted the license agreement
- Check that the correct Node.js version is installed (v14+ recommended)
- Verify that all dependencies were installed with npm install
Project operations failing
- Ensure the project path is correct and accessible
- Check that the project format is supported (standard Xcode project or workspace)
- Verify that you have the necessary permissions to access the project files
Build or test operations failing
- Ensure the Xcode command line tools are installed: xcode-select --install
- Check that the selected scheme exists in the project
- Verify that the project itself builds correctly in Xcode

Logs

The server logs can provide valuable information for troubleshooting:

Check the console output where the server is running
Adjust the LOG_LEVEL in the .env file for more detailed logs

Advanced Configuration

For advanced users, the server can be further customized:

Modify the tsconfig.json file to adjust TypeScript compilation options
Extend the server's functionality by adding new tools in the src directory
Configure custom build settings by modifying the build tool parameters

Updating

To update the server to the latest version:

Pull the latest changes:
```
git pull origin master
```
Install any new dependencies:
```
npm install
```
Rebuild the server:
```
npm run build
```
Restart the server:
```
npm start
```