Xcode MCP Server User Guide

This guide provides detailed instructions on how to effectively use the Xcode MCP Server with AI assistants. It covers common workflows, example prompts, and best practices.

Getting Started

After installing the server, you can start using it with any MCP-compatible AI assistant. This guide focuses on using it with Claude Desktop and Cursor, but the concepts apply to any MCP client.

Basic Workflow

Start the server using npm start
Connect your AI assistant to the server
Interact with your Xcode projects through the AI

Working with Projects

Setting Your Projects Directory

If you didn't set a projects directory during setup, you can do it through the AI:

Set my Xcode projects directory to /Users/username/Documents/XcodeProjects

The server will acknowledge the change and attempt to detect any projects in that directory.

Finding Projects

You can ask the AI to find Xcode projects in your directory:

Find all Xcode projects in my projects directory, including workspaces and Swift Package Manager projects

Viewing Active Project

You can ask about the currently active project:

What's my current active project? Show me its detailed information including configurations, targets, and schemes.

Setting Active Project

If the automatic project detection doesn't find your project, you can set it manually:

Set the active project to /Users/username/Documents/XcodeProjects/MyApp.xcodeproj

The server now supports different project types:

Set the active project to /Users/username/Documents/XcodeProjects/MyApp.xcworkspace

Or for Swift Package Manager projects:

Set the active project to /Users/username/Documents/SwiftPackages/MyPackage

You can also automatically open the project in Xcode when setting it as active:

Set the active project to /Users/username/Documents/XcodeProjects/MyApp.xcodeproj and open it in Xcode

This ensures that your manually set project and what's open in Xcode stay in sync.

Project Detection

The server can detect the active project opened in Xcode:

Detect the active Xcode project

By default, this command will respect any project you've already set manually. If you want to force it to check what's currently open in Xcode:

Detect the active Xcode project and force redetect even if one is already set

Directory Navigation

The server now has improved directory navigation. You can change directories:

Change directory to Sources/Models

Push directories onto a stack for easy navigation:

Push directory to Tests/UnitTests

And return to previous directories:

Pop directory to return to previous location

Check your current location:

What's my current directory?

Listing Project Files

You can ask to see files in the project:

List all Swift files in the current project

For more detailed information:

List files in the current directory with detailed information and include hidden files

File Operations

Reading Files

To view the content of a file:

Show me the contents of AppDelegate.swift

or

Let me see the implementation of the UserModel class

Getting File Information

To get detailed information about a file:

Get information about Package.swift

Modifying Files

You can ask the AI to create or modify files:

Create a new Swift file called ProfileViewModel with a basic MVVM structure

or

Add a function to handle user authentication in UserService.swift

File Management

You can now perform additional file operations:

Copy a file:

Copy the UserModel.swift file to Models/Legacy/UserModel.swift

Move a file:

Move the AppDelegate.swift file to the Application directory

Delete a file:

Delete the OldViewController.swift file

Create a directory:

Create a new directory called Networking/Services

Finding Files

You can find files matching patterns:

Find all Swift files containing "View" in their name

or

Find all JSON files in the Resources directory

Checking File Existence

Check if a file exists:

Does the file Configuration.json exist?

Finding Code

You can ask the AI to find specific code patterns:

Find all usages of UITableView in the project

or

Where are network requests being made in the app?

Building and Testing

Building the Project

To build your project:

Build the project using the 'Debug' configuration and 'MyApp' scheme

Running Tests

To run tests:

Run the tests for the current project

or

Run the unit tests in the 'UserModelTests' test suite

Static Analysis

You can use the static analyzer:

Analyze the NetworkManager.swift file for potential issues

CocoaPods Integration

Checking CocoaPods Status

To check if your project uses CocoaPods:

Check if this project uses CocoaPods and show me the installed pods

Installing Pods

To install CocoaPods dependencies:

Run pod install for the current project

Or with more options:

Run pod install with clean cache and repo update

Updating Pods

To update CocoaPods dependencies:

Update all pods in the project

or

Update only the Alamofire and SwiftyJSON pods

Checking Outdated Pods

To check for outdated pods:

Show me which pods are outdated in my project

Repo Management

To update CocoaPods repositories:

Update the CocoaPods spec repositories

Initializing Podfile

To create a new Podfile:

Initialize a new Podfile in the current project

Removing CocoaPods

To remove CocoaPods from a project:

Deintegrate CocoaPods from my project

Swift Package Manager

Initializing a Swift Package

To create a new Swift Package:

Initialize a new Swift Package in the current directory as a library called "MyLibrary"

With more options:

Initialize a new Swift Package called "MyTool" as an executable with XCTest support

Adding a Package Dependency

To add a new Swift Package dependency:

Add the Swift package at https://github.com/Alamofire/Alamofire.git with version from: 5.0.0

Or with specific version requirements:

Add the Swift package at https://github.com/apple/swift-log.git with version range: 1.0.0 to 1.5.0

Updating Packages

To update packages:

Update all Swift packages in this project

Or update a specific package:

Update the Alamofire package to the latest version

Building Swift Packages

To build a Swift Package:

Build the Swift package in release configuration

Testing Swift Packages

To run tests:

Test the Swift package with verbose output

Or with specific filters:

Run Swift package tests filtering for the "NetworkTests" test suite

Viewing Dependencies

To see package dependencies:

Show me the dependencies of this Swift package as a graph

Cleaning Build Artifacts

To clean up build files:

Clean the Swift package build artifacts

Dump Package Manifest

To see the package structure:

Dump the Package.swift manifest as JSON

Simulator Management

Listing Simulators

To see available simulators:

Show me all available iOS simulators

Working with Simulators

To boot a simulator:

Boot the simulator with UDID 12345678-1234-1234-1234-123456789012

To shut down a simulator:

Shut down the simulator with UDID 12345678-1234-1234-1234-123456789012

App Management

To install an app:

Install MyApp.app on the booted simulator

To launch an app:

Launch com.mycompany.MyApp on the simulator

To terminate an app:

Terminate the running MyApp on the simulator

Taking Screenshots

To capture a simulator screenshot:

Take a screenshot of the current simulator state

Recording Video

To record simulator activity:

Record a 30-second video of the simulator

Advanced Xcode Operations

Using Xcode Tools

To run specific Xcode tools:

Run the actool command to compile the Assets.xcassets file

Getting Xcode Information

To get information about the installed Xcode:

Show me information about my Xcode installation

Generating App Icons

To generate app icons:

Generate app icons from my source image icon.png

Debugging

To use LLDB:

Run LLDB with the command 'process attach --name "MyApp"'

Performance Tracing

To capture performance traces:

Capture a 10-second performance trace of MyApp.app

Path Management

The server now includes secure path management. You can:

Check Path Resolution

To see how a path would be resolved:

Resolve the path ../Resources/images

Navigating Directories

To change directories:

Change to the project's Source directory

To push directory for temporary navigation:

Push directory to Tests and then run the tests

To return to previous directory:

Pop directory to return where we were before

Example Workflows

Starting a New Feature

Here's an example conversation to create a new feature:

User: I need to add a user profile screen to my iOS app. It should display the user's name, email, profile picture, and settings.

AI: I'll help you add a user profile screen. First, let's check if you have a UserProfile model or something similar.

[AI uses tools to search the project for relevant files]

AI: I'll create the necessary files for a user profile feature using MVVM architecture:
1. A UserProfileModel
2. A UserProfileViewModel
3. A UserProfileViewController or SwiftUI View

[AI creates the files with appropriate implementations]

Debugging an Issue

Here's how debugging might look:

User: My app crashes when I try to load user data from the API. The crash happens in UserService.swift around line 45.

AI: Let me check that file to understand what's happening.

[AI reads the UserService.swift file]

AI: I see the issue. On line 47, you're force-unwrapping an optional value from the JSON response. If that value is nil, it would cause a crash.

Let me suggest a fix:

[AI modifies the code to safely handle the optional]

User: Can you also add some unit tests to verify this won't happen again?

AI: Certainly! I'll create unit tests for the UserService that specifically test handling missing data in the response.

[AI creates or modifies test files]

Working with Swift Packages

Here's an example of working with Swift Package Manager:

User: I need to create a new networking library as a Swift Package.

AI: I'll help you create a new Swift Package for networking. Let's first initialize a new package.

[AI initializes a new Swift Package]

AI: Now let's add some dependencies that will help with networking.

[AI adds dependencies like Alamofire]

AI: Let's create the basic structure for our networking library.

[AI creates network manager, request builders, etc.]

AI: Now let's write some tests to verify the functionality.

[AI creates tests for the networking features]

AI: Finally, let's build and test the package to make sure everything works.

[AI builds and tests the package]

Best Practices

Be Specific: When asking the AI to make changes, be specific about what you want. Include file names and clear requirements.
Use Directory Navigation: Use the directory navigation tools to move around your project structure efficiently.
Verify Changes: Always review the changes made by the AI before committing them to your production code.
Incremental Changes: Work with the AI in small, incremental steps rather than asking for massive changes all at once.
Project Context: When starting a new session, give the AI a brief overview of your project structure and architecture to help it make more informed decisions.
Follow Up: If the AI doesn't get something right the first time, follow up with clarifications rather than completely changing your approach.
Path References: Use relative paths based on your current directory when referring to files.

Troubleshooting

Server Not Finding Projects

If the server can't find your projects:

Make sure the projects directory path is correct
Check that the projects have the .xcodeproj or .xcworkspace extension
Try setting the active project path explicitly with set_project_path
Use the openInXcode: true parameter with set_project_path to ensure the project is open in Xcode
Use the find_projects tool to see what projects are detected
If detect_active_project is finding the wrong project, try using it without the forceRedetect parameter to respect your manual settings

Project Path Mismatch

If you're experiencing issues where detect_active_project finds a different project than what you set manually:

Use set_project_path with the openInXcode: true parameter to align what's open in Xcode with your server settings
By default, detect_active_project will respect your manual settings, but can be overridden with forceRedetect: true
Check that you're using the complete path to the project, including any subdirectories
Ensure that your project path doesn't end with /project.xcworkspace which is invalid for Xcode commands

Path Resolution Issues

If you encounter path-related errors:

Use get_current_directory to check your current location
Use resolve_path to see how paths are being resolved
Make sure paths are within allowed boundaries
Use directory navigation tools to position yourself correctly

Build Issues

If builds fail:

Verify that you're using a valid scheme and configuration
Check that the project builds normally in Xcode
Use get_project_configuration to see available schemes and configurations
Look for any dependency issues (CocoaPods, SPM)

File Operation Errors

If file operations fail:

Check file permissions
Verify the path is within the active project directory
Use check_file_exists to confirm file existence
Make sure the file exists when trying to modify it

Advanced Configuration

For advanced users, the .env file supports additional configuration options:

DEBUG: Enable detailed logging
MAX_CACHED_FILES: Control memory usage
PROJECTS_BASE_DIR: Set default projects directory
Custom project detection behavior

See the .env.example file for more details.

Getting Help

If you encounter issues with the Xcode MCP Server, you can:

Check the server logs for error messages
Refer to this guide and the Tools Overview
Use the path resolution and validation tools to debug path issues
File an issue on the GitHub repository

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!