Xcode MCP Server: AI Code & Project Automation

Overview

The Xcode MCP Server is a local server that exposes project-aware tools for AI-assisted development workflows in Xcode projects. It implements the Model Context Protocol (MCP) pattern so language models (or other automation agents) can safely read and modify a workspace, run builds and tests, and perform targeted file operations without giving the model direct access to the whole system.

This server is useful when you want to attach AI tooling to real-world Xcode projects: enabling code generation that respects project structure, automating repetitive tasks (build, run tests, update settings), or creating context-aware suggestions that operate on the actual files. It adds a controlled programmatic layer between a model and your workspace to improve developer productivity while reducing risk.

Features

• File operations: list, read, write, create, and delete files inside a workspace
• Project introspection: list targets, schemes, source trees, and project metadata
• Build and test automation: run xcodebuild or SwiftPM commands and stream results
• Command execution: run arbitrary (sandboxed) shell commands with output capture
• Patch/commit support: create patches, apply edits, and generate commit metadata
• Search & code context: code search, file-level context extraction, and snippet delivery
• Authentication & access control: API key and workspace restrictions for local usage
• Logging and diagnostics: request tracing, command results, and error reporting

Installation / Configuration

Minimum steps to get the server running locally. Replace and with your values.

1. Clone the repository:

git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

2. Build and run (example using Swift Package Manager; adjust if the project uses another tool):

swift build -c release
.build/release/xcode-mcp-server --workspace /path/to/your/xcode/project \
  --port 8080 --api-key "your-secret-key"

3. Example environment-based configuration:

export XCODE_MCP_WORKSPACE="/path/to/YourApp"
export XCODE_MCP_PORT=8080
export XCODE_MCP_API_KEY="your-secret-key"
.build/release/xcode-mcp-server

4. Simple systemd or launchd unit (conceptual):

• Provide the executable path and environment variables for workspace and API key.
• Ensure the service runs under an account that has filesystem access to the project.

Configuration options (typical):

• –workspace: path to the Xcode project or workspace root
• –port: listening port (default 8080)
• –api-key: required token for API access
• –log-level: debug | info | warn | error
• –sandbox: enable/disable restricted execution mode

Available Tools / Resources

The server exposes a set of tools/endpoints designed to be consumed via MCP-style requests or a simple REST API. Use these programmatically from a language model agent or automation script.

Tool name	Purpose
listFiles	Enumerate files under the workspace with filters (extensions, paths)
readFile	Return file contents and metadata
writeFile	Create or replace a file with given contents
applyPatch	Apply a unified diff or structured edit to files
search	Full-text or code-aware search across the workspace
openProject	Load and return project metadata (targets, schemes, settings)
build	Run xcodebuild or swift build for specified target/scheme
test	Run tests and stream test results
runCommand	Execute a shell command and capture stdout/stderr and exit code
createBranch	Create a git branch within the workspace
commit	Stage and commit changes, optionally push or create a patch

Basic example: read a file via curl

curl -s -X POST http://localhost:8080/api/readFile \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"path":"Sources/App/AppDelegate.swift"}'

Use Cases

• Context-aware code generation

  • Problem: Add a new view controller and wire it into the storyboard and project.
  • Workflow: Ask the AI agent to create the new Swift file, update the storyboard file, and apply a patch. The server’s readFile and applyPatch tools ensure generated changes align with existing conventions and file locations.

• Large-scale refactor

  • Problem: Rename a class and update all references in the project.
  • Workflow: Use search to collect occurrences, generate patch candidates, preview changes, then applyPatch to perform atomic edits. Commit or create a branch via createBranch and commit.

• Automating build/test workflows

  • Problem: Run a set of unit tests and collect diagnostics for failing cases.
  • Workflow: Trigger test via the test tool, stream results back to the agent, and have the agent propose focused fixes or test reconfiguration. The build/test tools provide exit codes and logs.

• Repetitive project maintenance

  • Problem: Update package versions or build settings across many targets.
  • Workflow: openProject to enumerate targets, generate per-target edits, then applyPatch and commit changes programmatically.

• Local CI helper for AI-assisted PRs

  • Problem: Generate a set of changes and prepare a pull request.
  • Workflow: Use writeFile/applyPatch to stage edits, createBranch to isolate work, and commit to create a tidy change set. Optionally export a patch or invoke an external GH CLI to open a PR.

Security and Best Practices

• Run the MCP server only on trusted machines or within secure networks.
• Always set an API key and restrict workspace paths to avoid accidental exposure.
• Prefer review: let the agent propose patches and present diffs for human approval before applying changes and committing.
• Use logging to capture actions and enable audit trails.

For the latest code, usage examples, and advanced configuration, see the project repository: https://github.com/r-huijts/xcode-mcp-server.