xcodeproj-mcp-server

# xcodeproj-mcp-server   [](https://developer.apple.com/xcode/) [](https://swift.org/package-manager/)  [ ](https://github.com/giginet/xcodeproj-mcp-server/blob/main/LICENSE.md) A Model Context Protocol (MCP) server for manipulating Xcode project files (.xcodeproj) using Swift.  ## Overview xcodeproj-mcp-server is an MCP server that provides tools for programmatically manipulating Xcode project files. It leverages the [tuist/xcodeproj](https://github.com/tuist/xcodeproj) library for reliable project file manipulation and implements the Model Context Protocol using the [swift-sdk](https://github.com/modelcontextprotocol/swift-sdk). This server enables AI assistants and other MCP clients to: - Create new Xcode projects - Manage targets, files, and build configurations - Inspect project structure including groups and hierarchies - Modify build settings - Add dependencies and frameworks - Automate common Xcode project tasks ## Use Cases ### Project Creation and Setup - **Create projects from scratch**: Generate new Xcode projects with custom configurations, bundle identifiers, and organization settings without opening Xcode - **Multi-target project scaffolding**: Set up complex projects with multiple apps, frameworks, tests, and extensions in a single automated workflow ### Development Workflow Automation - **Add new files to targets**: After creating a new Swift file, automatically add it to the appropriate target's source files for compilation - **Add folder references**: Include external resource folders or asset directories as synchronized folder references in your project, automatically reflecting any file system changes - **Add build phases**: Integrate code formatters, linters, or custom build scripts into your targets (e.g., SwiftLint, SwiftFormat execution phases) - **Create frameworks and app extensions**: Quickly scaffold new framework targets or app extensions for modularizing your codebase ### Project Configuration Management - **Automate Info.plist setup**: Programmatically configure Info.plist settings, entitlements, and provisioning profiles for different targets - **Build configuration management**: Set up different build configurations with appropriate compiler flags, bundle identifiers, and deployment targets - **Dependency management**: Add system frameworks, link libraries, and configure target dependencies without manual Xcode navigation ## How to set up for Claude Desktop and Claude Code ### Prerequisites - Docker - macOS (for running Xcode projects) ### Installation using Docker Pull the pre-built Docker image from GitHub Container Registry: ```bash docker pull ghcr.io/giginet/xcodeproj-mcp-server ``` ### Configuration for Claude Code ```bash # Add MCP server using Docker $ claude mcp add xcodeproj -- docker run --rm -i -v $PWD:/workspace ghcr.io/giginet/xcodeproj-mcp-server /workspace ``` We need to mount the current working directory (`$PWD`) to `/workspace` inside the container. This allows the server to access your Xcode projects. ### Configuration for Claude Desktop Add the following to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "xcodeproj": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "${workspaceFolder}:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server", "/workspace" ] } } } ``` ### Path Security The MCP server now supports restricting file operations to a specific base directory. When you provide a base path as a command-line argument: - All `project_path` and file path parameters will be resolved relative to this 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 especially useful when running the server in Docker containers or other sandboxed environments. ## Available Tools ### Project Management - **`create_xcodeproj`** - Create a new Xcode project - Parameters: `project_name`, `path`, `organization_name`, `bundle_identifier` - **`list_targets`** - List all targets in a project - Parameters: `project_path` - **`list_build_configurations`** - List all build configurations - Parameters: `project_path` - **`list_files`** - List all files in a specific target - Parameters: `project_path`, `target_name` - **`list_groups`** - List all groups in the project with hierarchical paths, optionally filtered by target - Parameters: `project_path`, `target_name` (optional) ### File Operations - **`add_file`** - Add a file to the project - Parameters: `project_path`, `file_path`, `target_name`, `group_path` - **`remove_file`** - Remove a file from the project - Parameters: `project_path`, `file_path` - **`move_file`** - Move or rename a file within the project - Parameters: `project_path`, `source_path`, `destination_path` - **`add_synchronized_folder`** - Add a synchronized folder reference to the project - Parameters: `project_path`, `folder_path`, `group_name`, `target_name` - **`create_group`** - Create a new group in the project navigator - Parameters: `project_path`, `group_name`, `parent_group_path` ### Target Management - **`add_target`** - Create a new target - Parameters: `project_path`, `target_name`, `type`, `platform`, `bundle_identifier` - **`remove_target`** - Remove an existing target - Parameters: `project_path`, `target_name` - **`duplicate_target`** - Duplicate an existing target - Parameters: `project_path`, `source_target_name`, `new_target_name` - **`add_dependency`** - Add dependency between targets - Parameters: `project_path`, `target_name`, `dependency_name` ### Build Configuration - **`get_build_settings`** - Get build settings for a target - Parameters: `project_path`, `target_name`, `configuration_name` - **`set_build_setting`** - Modify build settings - Parameters: `project_path`, `target_name`, `setting_name`, `value`, `configuration_name` - **`add_framework`** - Add framework dependencies - Parameters: `project_path`, `target_name`, `framework_name`, `embed` - **`add_build_phase`** - Add custom build phases - Parameters: `project_path`, `target_name`, `phase_type`, `name`, `script` ### Swift Package Management - **`add_swift_package`** - Add a Swift Package dependency to the project - Parameters: `project_path`, `package_url`, `requirement`, `target_name`, `product_name` - **`list_swift_packages`** - List all Swift Package dependencies in the project - Parameters: `project_path` - **`remove_swift_package`** - Remove a Swift Package dependency from the project - Parameters: `project_path`, `package_url`, `remove_from_targets` ## License This project is licensed under the MIT License.