⚒️ xcode-mcp

Drive Xcode with AI. Build, test, sign, simulate, profile and debug iOS/macOS projects — without touching Xcode.

xcode-mcp is a Model Context Protocol server that bridges AI coding assistants with Xcode. 46 tools, 5 resources, 4 prompts — full project control over stdio, hardened with input validation, atomic project-file writes, and a 25-test QA suite.

✨ Highlights

Related MCP server: Xcode MCP Server

📑 Contents

• Quick install

• AI client setup

• Server control

• Tools

• Resources & prompts

• Environment variables

• Project config file

• Architecture

• Security

• Development & QA

• Contributing

• License

🚀 Quick install

Requirements: macOS with Xcode 14+ (to run the tools), Node 18+, Python 3.8+ (installer only).

git clone https://github.com/Raunaksplanet/xcode-mcp-server
cd xcode-mcp-server
python3 install.py

That's it — the installer checks prerequisites, installs dependencies, builds TypeScript, asks for your .xcodeproj/.xcworkspace and target clients, registers the server, and smoke-tests the build.

# Non-interactive (CI friendly)
python3 install.py --project-path ~/Projects/MyApp.xcodeproj --clients all --yes

# Preview everything without touching disk
python3 install.py --dry-run

# Remote one-liner
curl -sL https://raw.githubusercontent.com/Raunaksplanet/xcode-mcp-server/main/install.py \
  | python3 - --project-path ~/Projects/MyApp.xcodeproj --clients all --yes

python3 install.py --help shows all flags (--no-deps, --no-build, --strict, --freebuff-global, …). Every config edit is backed up (*.bak.<timestamp>) and corrupt JSON is recovered, never deleted.

🤖 AI client setup

One script registers the xcode server everywhere — or pick clients à la carte:

node scripts/setup-clients.mjs --client all --project-path ~/Projects/MyApp.xcodeproj --scheme MyApp

npm run setup:opencode   # OpenCode
npm run setup:cline      # Cline
npm run setup:kilo       # Kilo Code
npm run setup:freebuff   # Freebuff / Codebuff CLI

Manual minimal entry (OpenCode flavor):

{
  "mcp": {
    "xcode": {
      "type": "local",
      "command": ["node", "/absolute/path/to/xcode-mcp/dist/index.js"],
      "environment": {
        "XCODE_PROJECT_PATH": "/path/to/YourApp.xcodeproj",
        "XCODE_DEFAULT_SCHEME": "YourApp"
      },
      "enabled": true
    }
  }
}

🔁 Restart your AI client after setup so it picks up the new MCP server.

🎛️ Server control

serverctl.py runs the server as a background daemon (macOS, Windows, Linux):

python3 serverctl.py start --project-path ~/Projects/MyApp.xcodeproj --scheme MyApp
python3 serverctl.py status                 # exit 0 = running, 1 = stopped
python3 serverctl.py status --json          # machine-readable
python3 serverctl.py logs --lines 50        # tail the log
python3 serverctl.py logs --follow          # tail -f (Ctrl+C to stop)
python3 serverctl.py restart
python3 serverctl.py stop                   # graceful SIGTERM → SIGKILL fallback
python3 serverctl.py run --project-path …   # foreground, for debugging

State lives in ~/.xcode-mcp/ (run/xcode-mcp.pid, logs/xcode-mcp.log) — override with --base-dir or $XCODE_MCP_HOME. start refuses duplicates (PID identity-verified), watches for early crashes and prints the log tail on failure; stale pidfiles are detected and cleaned.

🧰 Tools

Full signatures in TOOLS_REFERENCE.md.

xcode_open_project · xcode_get_project_info · xcode_list_targets · xcode_list_schemes · xcode_list_files · xcode_add_file · xcode_remove_file · xcode_get_build_settings · xcode_set_build_setting · xcode_resolve_packages

xcode_build · xcode_build_for_testing · xcode_archive · xcode_clean · xcode_get_build_errors · xcode_get_analyzer_results

xcode_list_simulators · xcode_boot_simulator · xcode_shutdown_simulator · xcode_install_app · xcode_launch_app · xcode_terminate_app · xcode_get_simulator_logs · xcode_screenshot_simulator · xcode_record_simulator · xcode_open_url_simulator · xcode_set_simulator_location · xcode_push_notification_simulator · xcode_reset_simulator

xcode_run_tests · xcode_run_single_test · xcode_get_test_results · xcode_get_code_coverage

xcode_read_file · xcode_write_file · xcode_edit_file · xcode_get_swift_symbols · xcode_format_file · xcode_search_in_project

xcode_list_certificates · xcode_list_provisioning_profiles · xcode_set_signing · xcode_validate_signing

xcode_get_warnings · xcode_profile_app · xcode_add_spm_package

📚 Resources & prompts

Resources — xcode://project/structure · xcode://project/settings · xcode://build/latest_log · xcode://build/errors · xcode://simulators/list

Prompts — fix_build_error · create_swift_feature · write_xctest · review_swift_code

🔧 Environment variables

⚙️ Project config file

Drop .xcode-mcp.json next to your .xcodeproj:

{
  "default_scheme": "MyApp",
  "default_simulator": "iPhone 16 Pro",
  "excluded_paths": ["Pods", "vendor"],
  "build_pre_hooks": ["echo 'Starting build...'"],
  "build_post_hooks": ["echo 'Build complete!'"],
  "custom_destinations": ["platform=iOS Simulator,name=iPhone 16,OS=latest"]
}

🏗️ Architecture

flowchart LR
    AI["AI client\n(OpenCode / Cline / Kilo / Freebuff)"] <-->|stdio · MCP| SRV["xcode-mcp server\nsrc/server.ts"]
    SRV --> T1["project / build / test tools"]
    SRV --> T2["simulator / signing tools"]
    SRV --> T3["code / diagnostics tools"]
    T1 & T2 & T3 --> LIB["lib/\nxcode_runner · pbxproj_parser/writer\nsimulator_manager · process_manager"]
    LIB --> XCODE["Xcode toolchain\nxcodebuild · xcrun simctl\nxctrace · codesign"]

xcode-mcp/
├── install.py            # cross-platform installer (macOS/Windows/Linux)
├── serverctl.py          # daemon control: start/stop/restart/status/logs/run
├── scripts/
│   └── setup-clients.mjs # per-client MCP registration
├── src/
│   ├── index.ts          # entry point
│   ├── server.ts         # MCP server setup
│   ├── tools/            # 46 tool implementations
│   ├── lib/              # xcode_runner, pbxproj_parser/writer,
│   │                     # simulator_manager, process_manager,
│   │                     # validation, build_log, config, logger …
│   ├── types/            # pbxproj / xcodebuild / simulator types
│   ├── resources/        # MCP resource providers
│   └── prompts/          # MCP prompt templates
├── tests/
│   └── qa.test.ts        # 25 QA tests (npm test)
└── TOOLS_REFERENCE.md    # full tool signatures & error codes

🛡️ Security

• All file paths validated against the project root (sibling-prefix escapes blocked)

• Every tool argument type/length-checked; validation failures return structured errors

• No shell execution anywhere — all subprocess calls use argv arrays (execFile, no shell:true)

• project.pbxproj writes are atomic (tmp + rename) with timestamped backups

• Concurrent xcodebuild calls serialized (max 2) to protect DerivedData

• Timeouts on every external process; output buffers capped

• Wipes scoped to the project's own DerivedData — never the global tree

• Certificates/keys never logged; npm audit --omit=dev clean

🧪 Development & QA

npm install
npm run typecheck   # strict tsc
npm test            # 25 tests: parser fixtures, writer round-trips,
                    # build-output parsing, validation helpers
npm run build       # tsup bundle → dist/
npm start           # run the server (needs XCODE_PROJECT_PATH)

🤝 Contributing

Issues and PRs welcome at Raunaksplanet/xcode-mcp-server. Please run npm run typecheck && npm test before submitting.

📄 License

MIT — see LICENSE.