xcode-mcp

MCP (Model Context Protocol) server that bridges AI assistants with Xcode, enabling full control over Xcode projects, builds, simulators, testing, and debugging — all without touching Xcode manually.

macOS only. Xcode 14+ required. Node 18+ required.

Quick Install

macOS / Linux:

curl -sL https://raw.githubusercontent.com/Raunaksplanet/xcode-mcp-server/main/install.sh | bash
# or locally:
./install.sh

Windows (PowerShell):

.\install.ps1

The installer: checks prerequisites, installs deps, builds, prompts for your Xcode project path, and registers with OpenCode automatically.

Manual Setup

npm install
npm run build
export XCODE_PROJECT_PATH=/path/to/YourApp.xcodeproj
npm start

OpenCode Integration

Clone the repo and add to ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["path/to/xcode-mcp/dist/index.js"],
      "env": {
        "XCODE_PROJECT_PATH": "/path/to/YourApp.xcodeproj",
        "XCODE_DEFAULT_SCHEME": "YourApp"
      }
    }
  }
}

Environment Variables

Configuration File

Place .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"]
}

Available Tools

Project Management

• xcode_open_project — Open project in Xcode

• xcode_get_project_info — Get project info (targets, schemes, configs)

• xcode_list_targets — List all targets

• xcode_list_schemes — List all schemes

• xcode_list_files — List project files

• xcode_add_file — Add file to project

• xcode_remove_file — Remove file from project

• xcode_get_build_settings — Get resolved build settings

• xcode_set_build_setting — Modify build settings

• xcode_resolve_packages — Resolve SPM dependencies

Build Tools

• xcode_build — Build the project

• xcode_build_for_testing — Build for testing

• xcode_archive — Archive for distribution

• xcode_clean — Clean build artifacts

• xcode_get_build_errors — Parse build errors/warnings

• xcode_get_analyzer_results — Run static analyzer

Simulator Control

• xcode_list_simulators — List available simulators

• xcode_boot_simulator — Boot a simulator

• xcode_shutdown_simulator — Shutdown simulator

• xcode_install_app — Install app on simulator

• xcode_launch_app — Launch app on simulator

• xcode_terminate_app — Terminate app

• xcode_get_simulator_logs — Fetch simulator logs

• xcode_screenshot_simulator — Take screenshot

• xcode_record_simulator — Record video

• xcode_open_url_simulator — Open URL (deep link testing)

• xcode_set_simulator_location — Set location

• xcode_push_notification_simulator — Simulate push notification

• xcode_reset_simulator — Reset to factory state

Testing

• xcode_run_tests — Run all tests

• xcode_run_single_test — Run specific test

• xcode_get_test_results — Parse xcresult bundle

• xcode_get_code_coverage — Get coverage report

Code Management

• xcode_read_file — Read file content

• xcode_write_file — Write file content

• xcode_edit_file — Find and replace in file

• xcode_get_swift_symbols — Extract Swift symbols

• xcode_format_file — Format with swift-format

• xcode_search_in_project — Search across project files

Code Signing

• xcode_list_certificates — List signing certificates

• xcode_list_provisioning_profiles — List provisioning profiles

• xcode_set_signing — Configure signing settings

• xcode_validate_signing — Verify code signature

Diagnostics

• xcode_get_warnings — Get build warnings

• xcode_profile_app — Profile with Instruments

• xcode_add_spm_package — Add SPM dependency

Resources

• xcode://project/structure — Project file tree

• xcode://project/settings — All build settings

• xcode://build/latest_log — Latest build log

• xcode://build/errors — Parsed build errors

• xcode://simulators/list — Available simulators

Prompts

• fix_build_error — Fix a build error with context

• create_swift_feature — Implement a Swift feature

• write_xctest — Generate XCTest cases

• review_swift_code — Swift best practices review

Architecture

xcode-mcp/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server setup
│   ├── tools/            # Tool implementations
│   ├── lib/              # Core libraries
│   │   ├── xcode_runner.ts    # xcodebuild/xcrun wrappers
│   │   ├── pbxproj_parser.ts  # PBXProject parser
│   │   ├── pbxproj_writer.ts  # PBXProject writer
│   │   ├── simulator_manager.ts # simctl wrapper
│   │   ├── process_manager.ts  # Process lifecycle
│   │   ├── logger.ts           # Structured logging
│   │   ├── error_handler.ts    # Error mapping
│   │   └── config.ts          # Configuration
│   ├── types/            # TypeScript type definitions
│   ├── resources/        # MCP resource providers
│   └── prompts/          # MCP prompt templates
├── package.json
└── tsconfig.json

Security

• All file paths are validated against the project root

• Command injection prevented via execFile with args arrays

• Sensitive data (certificates, keys) never logged

• Concurrent xcodebuild calls are queued (max 2)

• Path traversal detection on all file operations

License

MIT