XcodeProj MCP Server
About
An MCP server for manipulating Xcode project files (.xcodeproj) using Swift. Requires Docker and macOS.
Details
- Author
- giginet
- GitHub stars
- 133
- Downloads
- 260
- Categories
- Developer Tools, Other, File Management
Jump to
- Create new Xcode projects programmatically
- Manage targets, files, and build configurations
- Inspect project groups and hierarchies
- Add dependencies, frameworks, and Swift Packages
- Support for app extensions (widgets, etc.)
- Automate common Xcode development tasks
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
XcodeProj MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install via Docker: docker pull ghcr.io/giginet/xcodeproj-mcp-server. Configure for Claude Code with claude mcp add xcodeproj -- docker run --pull=always --rm -i -v $PWD:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace. For Claude Desktop, add a JSON entry to claude_desktop_config.json that runs the Docker container with the project directory mounted. The server supports path restriction to a base directory for security.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"xcodeproj mcp server": {
"xcodeproj": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"${workspaceFolder}:/workspace",
"ghcr.io/giginet/xcodeproj-mcp-server",
"/workspace"
]
}
}
}
}McpServers
{
"xcodeproj": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"${workspaceFolder}:/workspace",
"ghcr.io/giginet/xcodeproj-mcp-server",
"/workspace"
]
}
}A Model Context Protocol (MCP) server for manipulating Xcode project files (.xcodeproj) using Swift.
xcodeproj-mcp-server is an MCP server that provides tools for programmatically manipulating Xcode project files. It leverages thetuist/xcodeprojlibrary for reliable project file manipulation and implements the Model Context Protocol using theswift-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
- 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
- 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
- Add Widget Extensions: Automatically create and embed Widget Extension targets with proper configuration for iOS home screen widgets
- 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
- macOS (for running Xcode projects)
- A container runtime — eitherApple'scontainer(recommended) orDocker
The server is distributed as alinux/arm64container image, which runs on either runtime.
Setup with Apple'scontainer(recommended)
- A Mac with Apple silicon
- macOS 26 or later (containerdoes not support older versions)
Install thecontainerCLI from theofficial release page.
containerneeds its background service running. Start it once after installing, and again after each reboot:
Then pull the pre-built image from GitHub Container Registry:
container image pull ghcr.io/giginet/xcodeproj-mcp-server:latest
container runhas no--pulloption, so runcontainer image pullagain whenever you want to update to the latest image.
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/workspaceinside 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 runclaude mcp addfrom. It falls back to., the working directory Claude Code starts the server in, which is the project root.
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 thePATHof GUI applications.
container buildreads the sameDockerfile:
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 .
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
claude mcp add xcodeproj -- docker run --pull=always --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
As withcontainer, the project directory is mounted to/workspaceinside 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.
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", "${workspaceFolder}:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server", "/workspace" ] } } }
Using the server from Claude Code or Codex inside Xcode
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~/.claudeor~/.codexsetup. See Apple'sExtending and customizing agentsfor details.
Two things differ from the command-line setup:
- 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.
- Givecommandan absolute path, because the agent's environment does not necessarily have/usr/local/binon itsPATH.
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfigacts as Claude Code's configuration directory. PointCLAUDE_CONFIG_DIRat it and useclaude mcp add:
CLAUDE_CONFIG_DIR=~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig \ claude mcp add xcodeproj -s user -- \ /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
That writes the server intoClaudeAgentConfig/.claude.json. To add it by hand instead, add an entry undermcpServers:
{ "mcpServers": { "xcodeproj": { "type": "stdio", "command": "/usr/local/bin/container", "args": [ "run", "--rm", "-i", "-v", ".:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server:latest", "/workspace" ] } } }
~/Library/Developer/Xcode/CodingAssistant/codexacts as Codex'sCODEX_HOME:
CODEX_HOME=~/Library/Developer/Xcode/CodingAssistant/codex \ codex mcp add xcodeproj -- \ /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace
That writes the server intocodex/config.toml. To add it by hand instead:
[mcp_servers.xcodeproj] command = "/usr/local/bin/container" args = ["run", "--rm", "-i", "-v", ".:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server:latest", "/workspace"]
If you set up with Docker, use the absolute path to yourdockerbinary in place of/usr/local/bin/container. Restart the agent in Xcode after changing its configuration.
EnablingENABLE_TOOL_SEARCHin.claude/settings.jsonactivates dynamic MCP tool loading. This prevents unused MCP tools from consuming context.
{ "env": { "ENABLE_TOOL_SEARCH": "1" } }
The MCP server now supports restricting file operations to a specific base directory. When you provide a base path as a command-line argument:
- Allproject_pathand 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 containers or other sandboxed environments.
-
create_xcodeproj- Create a new Xcode project
- Parameters:project_name,path,organization_name,bundle_identifier
list_targets- List all targets in a project
list_build_configurations- List all build configurations
list_files- List all files in a specific target
list_groups- List all groups in the project with hierarchical paths, optionally filtered by target
- Parameters:project_path,target_name(optional)
- Parameters:project_path,file_path,target_name,group_path
remove_file- Remove a file from the project
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
- Parameters:project_path,target_name,type,platform,bundle_identifier
remove_target- Remove an existing target
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
-
add_app_extension- Add an App Extension target and embed it in a host app
- Parameters:project_path,extension_name,extension_type,host_target_name,bundle_identifier,platform(optional),deployment_target(optional)
- Supported extension types:widget,notification_service,notification_content,share,today,action,file_provider,intents,intents_ui,keyboard,photo_editing,document_provider,custom
remove_app_extension- Remove an App Extension target and its embedding from the host app
- Parameters:project_path,extension_name
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
