Xcode MCP Server for Reproducible Build Errors

Overview

This project provides a small Model Context Protocol (MCP) server focused on Xcode build contexts. It helps you capture and serve deterministic snapshots of an Xcode project (sources, build settings, DerivedData snippets, and toolchain metadata) so code-aware assistant models can reproduce and report identical build errors. When paired with assistants such as ClaudeCode or Cursor, the server makes it straightforward to get consistent, reproducible diagnostics from LLM-driven workflows.

Reproducible build errors are useful for debugging, triage, and customer support. Instead of sending fuzzy logs or hand-copying compiler flags, you create a versioned MCP bundle that contains all the context the model needs. The MCP server stores and serves these bundles through a simple HTTP API and integrates with model providers so that assistants receive a complete, machine-checkable context for deterministic error reproduction.

Features

• Capture Xcode project context (source files, selected DerivedData, build settings, toolchain metadata)
• Package context into an MCP-compatible bundle for deterministic reproduction
• HTTP server to store and serve MCP bundles and metadata
• Integrations for ClaudeCode and Cursor to enable model-driven, reproducible error analysis
• CLI and simple API for uploading, listing, and retrieving contexts
• Versioned snapshots so teams can reference the exact state that produced an error

Installation / Configuration

Basic setup is straightforward. The repository includes a minimal server and a small CLI for packaging Xcode contexts into MCP bundles.

1. Clone the repository:

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

2. Build and run with Docker (recommended for isolation):

# Build the container
docker build -t xcode-mcp-server .

# Run the server (example exposes port 8080)
docker run -p 8080:8080 \
  -e CLAUDE_API_KEY="${CLAUDE_API_KEY}" \
  -e CURSOR_API_KEY="${CURSOR_API_KEY}" \
  -v "$(pwd)/data:/data" \
  xcode-mcp-server

3. Or run locally using Node/Python runtime (if provided by project):

# Example for a Node-based server; adapt to the actual runtime in repo
npm install
npm run start

4. Environment variables

Use these environment variables to enable model provider integrations and control server behavior:

5. Packaging an Xcode context

The repository includes a CLI to package a project directory into an MCP bundle. Example (adjust flags for your project layout):

# Create a bundle named myapp.mcpbundle from an Xcode project folder
./xcode-mcp package \
  --project ./MyApp/MyApp.xcodeproj \
  --derived-data ~/Library/Developer/Xcode/DerivedData/MyApp-xxxx \
  --output ./myapp.mcpbundle

6. Upload the bundle to the server

curl -X POST -F "[email protected]" http://localhost:8080/api/bundles

The server will return an ID you can use to fetch or reference this snapshot.

Available Tools / Resources

• GitHub repo: https://github.com/drewster99/xcode-mcp-server
• Included CLI: package, list, inspect, and delete MCP bundles
• HTTP API: basic endpoints for uploading bundles, listing stored snapshots, and fetching by ID
• Model adapters: example code showing how to pass MCP bundles to ClaudeCode and Cursor for reproducible analysis
• Storage backend: filesystem-based storage with optional mounting to external volumes (suitable for CI)

Refer to the repo for detailed examples and the exact API contract used by the server.

Use Cases

• CI snapshotting for flaky builds: Capture the exact project state, push the bundle into an artifact store, and let an assistant reproduce the failing build to determine whether the issue is environmental or code-related.
• Customer support reproducibility: Ask a user to upload an MCP bundle or collect one automatically from diagnostics. Support engineers and model assistants can reproduce the same compiler output, making triage faster and more reliable.
• Automated bug reports: When a build error occurs in nightly runs, automatically create an MCP bundle and open a reproducible issue including a link to the bundle. AI assistants can attach deterministic reproduction steps and suggested fixes.
• Model-driven debugging: Give ClaudeCode or Cursor the MCP bundle to generate identical compile logs and targeted suggestions (e.g., fix import paths, flags, or third-party mismatches) while avoiding “works on my machine” ambiguity.

Quick Example Workflow

1. Developer runs a local packaging command to create myapp.m