Xcode Project Manager MCP server for AI agents

The xcodeproj-mcp-server is a powerful Model Context Protocol (MCP) server that allows you to programmatically manipulate Xcode project files (.xcodeproj) using Swift. It provides AI assistants and MCP clients with the ability to create, inspect, and modify Xcode projects without directly opening Xcode.

Installation

Prerequisites

Docker
macOS (for running Xcode projects)

Installing with Docker

Pull the pre-built Docker image from GitHub Container Registry:

docker pull ghcr.io/giginet/xcodeproj-mcp-server

Configuration

Setting Up for Claude Code

Configure the MCP server for Claude Code with this command:

# Add MCP server using Docker
claude mcp add xcodeproj -- docker run --rm -i -v $PWD:/workspace ghcr.io/giginet/xcodeproj-mcp-server /workspace

This mounts your current working directory ($PWD) to /workspace inside the container, allowing the server to access your Xcode projects.

Setting Up for Claude Desktop

Add the following to your Claude Desktop configuration file located at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xcodeproj": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server",
        "/workspace"
      ]
    }
  }
}

Path Security

The server supports restricting file operations to a specific base directory:

All paths will be resolved relative to the provided base path
Absolute paths are validated to ensure they're within the base directory
Any attempt to access files outside the base directory will result in an error

This is particularly useful when running the server in Docker containers or other sandboxed environments.

Available Tools

Project Management

Creating a New Project

create_xcodeproj

Parameters:

project_name - Name of the new project
path - Where to create the project
organization_name - Organization name for the project
bundle_identifier - Bundle identifier (e.g., com.example.appname)

Listing Project Elements

list_targets

Parameters:

project_path - Path to the .xcodeproj file

list_build_configurations

Parameters:

project_path - Path to the .xcodeproj file

list_files

Parameters:

project_path - Path to the .xcodeproj file
target_name - Name of the target to list files for

list_groups

Parameters:

project_path - Path to the .xcodeproj file
target_name (optional) - Filter by target name

File Operations

Adding Files

add_file

Parameters:

project_path - Path to the .xcodeproj file
file_path - Path to the file to add
target_name - Target to add the file to
group_path - Path of the group to add the file to

Managing Files

remove_file

Parameters:

project_path - Path to the .xcodeproj file
file_path - Path to the file to remove

move_file

Parameters:

project_path - Path to the .xcodeproj file
source_path - Current path of the file
destination_path - New path for the file

add_synchronized_folder

Parameters:

project_path - Path to the .xcodeproj file
folder_path - Path to the folder to add
group_name - Name of the group to create
target_name - Target to add the folder to

create_group

Parameters:

project_path - Path to the .xcodeproj file
group_name - Name of the new group
parent_group_path - Path of the parent group

Target Management

Creating and Modifying Targets

add_target

Parameters:

project_path - Path to the .xcodeproj file
target_name - Name for the new target
type - Target type (e.g., application, framework)
platform - Platform (e.g., iOS, macOS)
bundle_identifier - Bundle identifier for the target

remove_target

Parameters:

project_path - Path to the .xcodeproj file
target_name - Name of the target to remove

duplicate_target

Parameters:

project_path - Path to the .xcodeproj file
source_target_name - Name of the target to duplicate
new_target_name - Name for the duplicated target

add_dependency

Parameters:

project_path - Path to the .xcodeproj file
target_name - Name of the dependent target
dependency_name - Name of the target to depend on

Build Configuration

Managing Build Settings

get_build_settings

Parameters:

project_path - Path to the .xcodeproj file
target_name - Target to get settings for
configuration_name - Build configuration (e.g., Debug, Release)

set_build_setting

Parameters:

project_path - Path to the .xcodeproj file
target_name - Target to modify
setting_name - Name of the build setting
value - New value for the setting
configuration_name - Build configuration to modify

add_framework

Parameters:

project_path - Path to the .xcodeproj file
target_name - Target to add the framework to
framework_name - Name of the framework
embed - Whether to embed the framework

add_build_phase

Parameters:

project_path - Path to the .xcodeproj file
target_name - Target to add the phase to
phase_type - Type of build phase
name - Name for the build phase
script - Script content (for script phases)

Swift Package Management

Managing Swift Packages

add_swift_package

Parameters:

project_path - Path to the .xcodeproj file
package_url - URL of the Swift Package
requirement - Version requirement
target_name - Target to add the package to
product_name - Name of the product to use

list_swift_packages

Parameters:

project_path - Path to the .xcodeproj file

remove_swift_package

Parameters:

project_path - Path to the .xcodeproj file
package_url - URL of the package to remove
remove_from_targets - Whether to remove from all targets

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "xcodeproj" '{"command":"docker","args":["run","--rm","-i","-v","${workspaceFolder}:/workspace","ghcr.io/giginet/xcodeproj-mcp-server","/workspace"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "xcodeproj": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-v",
                "${workspaceFolder}:/workspace",
                "ghcr.io/giginet/xcodeproj-mcp-server",
                "/workspace"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "xcodeproj": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-v",
                "${workspaceFolder}:/workspace",
                "ghcr.io/giginet/xcodeproj-mcp-server",
                "/workspace"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect