Skip to content
Back to search

xcodeproj-mcp-server

A Model Context Protocol Server to manipulate *.xcodeproj

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/giginet--xcodeproj-mcp-server/badge.svg)](/listings/giginet--xcodeproj-mcp-server)

HTML

<a href="/listings/giginet--xcodeproj-mcp-server"><img src="/api/listings/giginet--xcodeproj-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS (for running Xcode projects) - A container runtime — either [Apple's `container`](#setup-with-apples-container-recommended) (recommended) or [Docker](#setup-with-docker)

The server is distributed as a `linux/arm64` container image, which runs on either runtime.

Setup with Apple's `container` (recommended)

[`container`](https://github.com/apple/container) is Apple's own tool for running Linux containers as lightweight virtual machines on macOS. It is the recommended runtime for this server: it comes from Apple, requires no third-party desktop application, and runs the published `linux/arm64` image natively on Apple silicon.

Requirements

- A Mac with Apple silicon - macOS 26 or later (`container` does not support older versions)

Installation

Install the `container` CLI from the [official release page](https://github.com/apple/container/releases).

`container` needs its background service running. Start it once after installing, and again after each reboot:

container system start

Then pull the pre-built image from GitHub Container Registry:

container image pull ghcr.io/giginet/xcodeproj-mcp-server:latest

`container run` has no `--pull` option, so run `container image pull` again whenever you want to update to the latest image.

Configuration for Claude Code

claude mcp add xcodeproj -- container run --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

This mounts the project directory to `/workspace` inside the container, which is how the server gets access to your Xcode projects. Keep the single quotes: they stop your shell from expanding the mount at registration time, so Claude Code resolves it every time it launches the server instead of pinning it to the directory you happened to run `claude mcp add` from. It falls back to `.`, the working directory Claude Code starts the server in, which is the project root.

Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

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

The installer places the binary at `/usr/local/bin/container`. The absolute path is used here because that directory is not always on the `PATH` of GUI applications.

Building the image locally

`container build` reads the same `Dockerfile`:

container build -t xcodeproj-mcp-server:local .

The builder container defaults to 2 CPUs and 2 GB of memory. Allocate more to it to speed up the release build:

container build -c 8 -m 8g -t xcodeproj-mcp-server:local .

Setup with Docker

Use Docker if you are on macOS 15 or earlier, or if Docker is already part of your workflow.

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

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

Configuration for Claude Code

claude mcp add xcodeproj -- docker run --pull=always --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

As with `container`, the project directory is mounted to `/workspace` inside the container so that the server can access your Xcode projects, and the single quotes keep the mount unexpanded until Claude Code launches the server.

Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "xcodeproj": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 344 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # xcodeproj-mcp-server
  2. ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/giginet/xcodeproj-mcp-server/tests.yml?style=flat-square&logo=github)
  3. ![Swift 6.1](https://img.shields.io/badge/Swift-6.1-FA7343?logo=swift&style=flat-square)
  4. [![Xcode 16.4](https://img.shields.io/badge/Xcode-16.4-16C5032a?style=flat-square&logo=xcode&link=https%3A%2F%2Fdeveloper.apple.com%2Fxcode%2F)](https://developer.apple.com/xcode/)
  5. [![SwiftPM](https://img.shields.io/badge/SwiftPM-compatible-green?logo=swift&style=flat-square)](https://swift.org/package-manager/)
  6. ![Platforms](https://img.shields.io/badge/Platform-macOS-lightgray?logo=apple&style=flat-square)
  7. [![License](https://img.shields.io/badge/License-MIT-darkgray?style=flat-square)
  8. ](https://github.com/giginet/xcodeproj-mcp-server/blob/main/LICENSE.md)
  9. A Model Context Protocol (MCP) server for manipulating Xcode project files (.xcodeproj) using Swift.
  10. ![Adding Post Build Phase for all targets](Documentation/demo.png)
  11. ## Overview
  12. 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).
  13. This server enables AI assistants and other MCP clients to:
  14. - Create new Xcode projects
  15. - Manage targets, files, and build configurations
  16. - Inspect project structure including groups and hierarchies
  17. - Modify build settings
  18. - Add dependencies and frameworks
  19. - Automate common Xcode project tasks
  20. ## Use Cases
  21. ### Project Creation and Setup
  22. - **Create projects from scratch**: Generate new Xcode projects with custom configurations, bundle identifiers, and organization settings without opening Xcode
  23. - **Multi-target project scaffolding**: Set up complex projects with multiple apps, frameworks, tests, and extensions in a single automated workflow
  24. ### Development Workflow Automation
  25. - **Add new files to targets**: After creating a new Swift file, automatically add it to the appropriate target's source files for compilation
  26. - **Add folder references**: Include external resource folders or asset directories as synchronized folder references in your project, automatically reflecting any file system changes
  27. - **Add build phases**: Integrate code formatters, linters, or custom build scripts into your targets (e.g., SwiftLint, SwiftFormat execution phases)
  28. - **Create frameworks and app extensions**: Quickly scaffold new framework targets or app extensions for modularizing your codebase
  29. - **Add Widget Extensions**: Automatically create and embed Widget Extension targets with proper configuration for iOS home screen widgets
  30. ### Project Configuration Management
  31. - **Automate Info.plist setup**: Programmatically configure Info.plist settings, entitlements, and provisioning profiles for different targets
  32. - **Build configuration management**: Set up different build configurations with appropriate compiler flags, bundle identifiers, and deployment targets
  33. - **Dependency management**: Add system frameworks, link libraries, and configure target dependencies without manual Xcode navigation
  34. ## How to set up for Claude Desktop and Claude Code
  35. ### Prerequisites
  36. - macOS (for running Xcode projects)
  37. - A container runtime — either [Apple's `container`](#setup-with-apples-container-recommended) (recommended) or [Docker](#setup-with-docker)
  38. The server is distributed as a `linux/arm64` container image, which runs on either runtime.
  39. ### Setup with Apple's `container` (recommended)
  40. [`container`](https://github.com/apple/container) is Apple's own tool for running Linux containers as lightweight virtual machines on macOS. It is the recommended runtime for this server: it comes from Apple, requires no third-party desktop application, and runs the published `linux/arm64` image natively on Apple silicon.
  41. #### Requirements
  42. - A Mac with Apple silicon
  43. - macOS 26 or later (`container` does not support older versions)
  44. #### Installation
  45. Install the `container` CLI from the [official release page](https://github.com/apple/container/releases).
  46. `container` needs its background service running. Start it once after installing, and again after each reboot:
  47. ```bash
  48. container system start
  49. ```
  50. Then pull the pre-built image from GitHub Container Registry:
  51. ```bash
  52. container image pull ghcr.io/giginet/xcodeproj-mcp-server:latest
  53. ```
  54. `container run` has no `--pull` option, so run `container image pull` again whenever you want to update to the latest image.
  55. #### Configuration for Claude Code
  56. ```bash
  57. claude mcp add xcodeproj -- container run --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
  58. ```
  59. This mounts the project directory to `/workspace` inside the container, which is how the server gets access to your Xcode projects. Keep the single quotes: they stop your shell from expanding the mount at registration time, so Claude Code resolves it every time it launches the server instead of pinning it to the directory you happened to run `claude mcp add` from. It falls back to `.`, the working directory Claude Code starts the server in, which is the project root.
  60. #### Configuration for Claude Desktop
  61. Add the following to your Claude Desktop configuration file:
  62. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  63. ```json
  64. {
  65. "mcpServers": {
  66. "xcodeproj": {
  67. "command": "/usr/local/bin/container",
  68. "args": [
  69. "run",
  70. "--rm",
  71. "-i",
  72. "-v",
  73. "${workspaceFolder}:/workspace",
  74. "ghcr.io/giginet/xcodeproj-mcp-server",
  75. "/workspace"
  76. ]
  77. }
  78. }
  79. }
  80. ```
  81. The installer places the binary at `/usr/local/bin/container`. The absolute path is used here because that directory is not always on the `PATH` of GUI applications.
  82. #### Building the image locally
  83. `container build` reads the same `Dockerfile`:
  84. ```bash
  85. container build -t xcodeproj-mcp-server:local .
  86. ```
  87. The builder container defaults to 2 CPUs and 2 GB of memory. Allocate more to it to speed up the release build:
  88. ```bash
  89. container build -c 8 -m 8g -t xcodeproj-mcp-server:local .
  90. ```
  91. ### Setup with Docker
  92. Use Docker if you are on macOS 15 or earlier, or if Docker is already part of your workflow.
  93. Pull the pre-built Docker image from GitHub Container Registry:
  94. ```bash
  95. docker pull ghcr.io/giginet/xcodeproj-mcp-server
  96. ```
  97. #### Configuration for Claude Code
  98. ```bash
  99. claude mcp add xcodeproj -- docker run --pull=always --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
  100. ```
  101. As with `container`, the project directory is mounted to `/workspace` inside the container so that the server can access your Xcode projects, and the single quotes keep the mount unexpanded until Claude Code launches the server.
  102. #### Configuration for Claude Desktop
  103. Add the following to your Claude Desktop configuration file:
  104. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  105. ```json
  106. {
  107. "mcpServers": {
  108. "xcodeproj": {
  109. "command": "docker",
  110. "args": [
  111. "run",
  112. "--rm",
  113. "-i",
  114. "-v",
  115. "${workspaceFolder}:/workspace",
  116. "ghcr.io/giginet/xcodeproj-mcp-server",
  117. "/workspace"
  118. ]
  119. }
  120. }
  121. }
  122. ```
  123. ### Using the server from Claude Code or Codex inside Xcode
  124. Xcode can run Claude Code and Codex as coding agents, and it reads their configuration from agent-specific subfolders of `~/Library/Developer/Xcode/CodingAssistant`, a folder Xcode uses exclusively. Configuration placed there affects agents only when you launch them in Xcode, so it does not interfere with your regular `~/.claude` or `~/.codex` setup. See Apple's [Extending and customizing agents](https://developer.apple.com/documentation/xcode/extending-and-customizing-agents#Customize-agent-environments) for details.
  125. Two things differ from the command-line setup:
  126. - Xcode launches the MCP server with the project directory as its working directory, so mount `.` directly. Codex has no equivalent of Claude Code's `${CLAUDE_PROJECT_DIR:-.}` expansion, so this keeps both agents on the same mount.
  127. - Give `command` an absolute path, because the agent's environment does not necessarily have `/usr/local/bin` on its `PATH`.
  128. #### Claude Code in Xcode
  129. `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig` acts as Claude Code's configuration directory. Point `CLAUDE_CONFIG_DIR` at it and use `claude mcp add`:
  130. ```bash
  131. CLAUDE_CONFIG_DIR=~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig \
  132. claude mcp add xcodeproj -s user -- \
  133. /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
  134. ```
  135. That writes the server into `ClaudeAgentConfig/.claude.json`. To add it by hand instead, add an entry under `mcpServers`:
  136. ```json
  137. {
  138. "mcpServers": {
  139. "xcodeproj": {
  140. "type": "stdio",
  141. "command": "/usr/local/bin/container",
  142. "args": [
  143. "run",
  144. "--rm",
  145. "-i",
  146. "-v",
  147. ".:/workspace",
  148. "ghcr.io/giginet/xcodeproj-mcp-server:latest",
  149. "/workspace"
  150. ]
  151. }
  152. }
  153. }
  154. ```
  155. #### Codex in Xcode
  156. `~/Library/Developer/Xcode/CodingAssistant/codex` acts as Codex's `CODEX_HOME`:
  157. ```bash
  158. CODEX_HOME=~/Library/Developer/Xcode/CodingAssistant/codex \
  159. codex mcp add xcodeproj -- \
  160. /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
  161. ```
  162. That writes the server into `codex/config.toml`. To add it by hand instead:
  163. ```toml
  164. [mcp_servers.xcodeproj]
  165. command = "/usr/local/bin/container"
  166. args = ["run", "--rm", "-i", "-v", ".:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server:latest", "/workspace"]
  167. ```
  168. If you set up with Docker, use the absolute path to your `docker` binary in place of `/usr/local/bin/container`. Restart the agent in Xcode after changing its configuration.
  169. ### Recommended settings for Claude Code
  170. Enabling `ENABLE_TOOL_SEARCH` in `.claude/settings.json` activates dynamic MCP tool loading. This prevents unused MCP tools from consuming context.
  171. ```json
  172. {
  173. "env": {
  174. "ENABLE_TOOL_SEARCH": "1"
  175. }
  176. }
  177. ```
  178. ### Path Security
  179. The MCP server now supports restricting file operations to a specific base directory. When you provide a base path as a command-line argument:
  180. - All `project_path` and file path parameters will be resolved relative to this base path
  181. - Absolute paths are validated to ensure they're within the base directory
  182. - Any attempt to access files outside the base directory will result in an error
  183. This is especially useful when running the server in containers or other sandboxed environments.
  184. ## Available Tools
  185. ### Project Management
  186. - **`create_xcodeproj`** - Create a new Xcode project
  187. - Parameters: `project_name`, `path`, `organization_name`, `bundle_identifier`
  188. - **`list_targets`** - List all targets in a project
  189. - Parameters: `project_path`
  190. - **`list_build_configurations`** - List all build configurations
  191. - Parameters: `project_path`
  192. - **`list_files`** - List all files in a specific target
  193. - Parameters: `project_path`, `target_name`
  194. - **`list_groups`** - List all groups in the project with hierarchical paths, optionally filtered by target
  195. - Parameters: `project_path`, `target_name` (optional)
  196. ### File Operations
  197. - **`add_file`** - Add a file to the project
  198. - Parameters: `project_path`, `file_path`, `target_name`, `group_path`
  199. - **`remove_file`** - Remove a file from the project
  200. - Parameters: `project_path`, `file_path`
  201. - **`move_file`** - Move or rename a file within the project
  202. - Parameters: `project_path`, `source_path`, `destination_path`
  203. - **`add_synchronized_folder`** - Add a synchronized folder reference to the project
  204. - Parameters: `project_path`, `folder_path`, `group_name`, `target_name`
  205. - **`create_group`** - Create a new group in the project navigator
  206. - Parameters: `project_path`, `group_name`, `parent_group_path`
  207. ### Target Management
  208. - **`add_target`** - Create a new target
  209. - Parameters: `project_path`, `target_name`, `type`, `platform`, `bundle_identifier`
  210. - **`remove_target`** - Remove an existing target
  211. - Parameters: `project_path`, `target_name`
  212. - **`duplicate_target`** - Duplicate an existing target
  213. - Parameters: `project_path`, `source_target_name`, `new_target_name`
  214. - **`add_dependency`** - Add dependency between targets
  215. - Parameters: `project_path`, `target_name`, `dependency_name`
  216. ### App Extension Management
  217. - **`add_app_extension`** - Add an App Extension target and embed it in a host app
  218. - Parameters: `project_path`, `extension_name`, `extension_type`, `host_target_name`, `bundle_identifier`, `platform` (optional), `deployment_target` (optional)
  219. - Supported extension types: `widget`, `notification_service`, `notification_content`, `share`, `today`, `action`, `file_provider`, `intents`, `intents_ui`, `keyboard`, `photo_editing`, `document_provider`, `custom`
  220. - **`remove_app_extension`** - Remove an App Extension target and its embedding from the host app
  221. - Parameters: `project_path`, `extension_name`
  222. ### Build Configuration
  223. - **`get_build_settings`** - Get build settings for a target
  224. - Parameters: `project_path`, `target_name`, `configuration_name`
  225. - **`set_build_setting`** - Modify build settings
  226. - Parameters: `project_path`, `target_name`, `setting_name`, `value`, `configuration_name`
  227. - **`add_framework`** - Add framework dependencies
  228. - Parameters: `project_path`, `target_name`, `framework_name`, `embed`
  229. - **`add_build_phase`** - Add custom build phases
  230. - Parameters: `project_path`, `target_name`, `phase_type`, `name`, `script`
  231. ### Swift Package Management
  232. - **`add_swift_package`** - Add a Swift Package dependency to the project
  233. - Parameters: `project_path`, `package_url`, `requirement`, `target_name`, `product_name`
  234. - **`list_swift_packages`** - List all Swift Package dependencies in the project
  235. - Parameters: `project_path`
  236. - **`remove_swift_package`** - Remove a Swift Package dependency from the project
  237. - Parameters: `project_path`, `package_url`, `remove_from_targets`
  238. ## License
  239. This project is licensed under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.