xcode-pilot-mcp

A comprehensive Model Context Protocol (MCP) server for iOS and macOS development. Provides 67 tools across 11 categories that give AI assistants full control over the Xcode development lifecycle — from building and testing to simulator management, app deployment, code signing, and more.

The iOS equivalent of android-pilot-mcp.

Table of Contents

• Features
• Requirements
• Quick Start
• Editor Setup
• Usage Examples
• Prompt Cookbook
• Tool Reference
• Architecture
• Development
• License

Features

| Category | Tools | Description | | ------------------------- | :---: | -------------------------------------------------------------------- | | Build & Compile | 8 | Build, clean, archive, export IPA, run tests with xcodebuild | | Simulator Management | 10 | Create, boot, shutdown, delete, clone simulators with xcrun simctl | | App Lifecycle | 8 | Install, launch, terminate apps, manage permissions | | Debugging & Logging | 7 | Stream logs, capture screenshots, record screen, accessibility audit | | Simulator Environment | 6 | Set GPS location, send push notifications, override status bar | | Code Signing | 5 | List identities, inspect provisioning profiles, check entitlements | | Package Management | 6 | SPM resolve/update, CocoaPods install/update/outdated | | Project Scaffolding | 5 | Create projects, generate SwiftUI views, ViewModels, widgets | | IPA Analysis | 4 | Inspect IPA contents, permissions, binary size, dSYM verification | | Code Quality | 4 | SwiftLint, swift-format, build warnings extraction | | Physical Devices | 4 | List, install, launch apps on connected iOS devices via devicectl |

Requirements

• macOS (required — Xcode tools are macOS-only)
• Node.js >= 20
• Xcode installed from the App Store
• Xcode Command Line Tools — install with:

  xcode-select --install

Optional tools (for specific features)

| Tool | Install | Used by | | ------------ | --------------------------- | ------------------------------------------- | | SwiftLint | brew install swiftlint | swiftlint_run, swiftlint_fix | | swift-format | brew install swift-format | swift_format_run | | CocoaPods | gem install cocoapods | pod_install, pod_update, pod_outdated |

Quick Start

Install globally

npm install -g xcode-pilot-mcp

Or run directly with npx

npx xcode-pilot-mcp

Verify installation

# The server starts on stdio — it will listen for MCP messages
xcode-pilot-mcp

Editor Setup

Claude Code

claude mcp add xcode-pilot -- npx xcode-pilot-mcp

Cursor

Add to your MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "xcode-pilot": {
      "command": "npx",
      "args": ["-y", "xcode-pilot-mcp"]
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "xcode-pilot": {
      "command": "npx",
      "args": ["-y", "xcode-pilot-mcp"]
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "xcode-pilot": {
      "command": "npx",
      "args": ["-y", "xcode-pilot-mcp"]
    }
  }
}

Local development

Use the .mcp.json at the project root:

{
  "mcpServers": {
    "xcode-pilot": {
      "command": "node",
      "args": ["build/index.js"],
      "transportType": "stdio"
    }
  }
}

Usage Examples

Build and test a project

"Build my iOS app with the Debug configuration for the iPhone 16 simulator"
→ Uses xcode_build with scheme, configuration, and destination

"Run all unit tests for the MyApp scheme"
→ Uses xcode_test with the appropriate destination

"Run only the LoginTests test class, skip SlowTests"
→ Uses xcode_test with onlyTesting and skipTesting filters

Manage simulators

"List all available simulators"
→ Uses simulator_list to show all devices with their state

"Create a new iPhone 16 Pro simulator with iOS 18"
→ Uses simulator_list_device_types + simulator_list_runtimes to find IDs,
  then simulator_create

"Boot the simulator and install my app"
→ Uses simulator_boot, then app_install with the .app path

Debug and capture

"Take a screenshot of the simulator"
→ Uses screenshot, returns the file path

"Record the simulator screen for 15 seconds"
→ Uses screen_record with duration=15

"Show me the last 5 minutes of logs for my app"
→ Uses log_collect with last="5m" and predicate filter

"Stream live logs from the simulator for 10 seconds"
→ Uses log_stream with timeout=10

App lifecycle

"Launch com.example.myapp on the booted simulator"
→ Uses app_launch with the bundle ID

"Grant camera permission to my app"
→ Uses app_privacy with action="grant", service="camera"

"Open a deep link: myapp://settings/profile"
→ Uses app_open_url with the custom URL scheme

"Where is my app's data stored?"
→ Uses app_get_container with container="data"

Environment simulation

"Set the simulator location to San Francisco"
→ Uses location_set with latitude=37.7749, longitude=-122.4194

"Send a test push notification with title 'Hello'"
→ Uses push_notification with APNs JSON payload

"Set the status bar to 9:41, full battery, full wifi"
→ Uses status_bar_override with time, batteryLevel, wifiBars

"Switch the simulator to dark mode"
→ Uses device_appearance with appearance="dark"

Code signing

"List all my code signing identities"
→ Uses signing_identities

"Show me all installed provisioning profiles"
→ Uses provisioning_profiles with summary for each

"Inspect the entitlements of my built app"
→ Uses entitlements_check on the .app bundle

Package management

"Resolve all SPM dependencies"
→ Uses spm_resolve

"Update my CocoaPods and check for outdated pods"
→ Uses pod_update then pod_outdated

"Show me the dependency tree for my Swift package"
→ Uses spm_show_dependencies with JSON format

Scaffolding

"Create a new SwiftUI iOS project called WeatherApp"
→ Uses project_create with template="swiftui", platform="ios"

"Generate a SwiftUI view called SettingsView with a preview"
→ Uses scaffold_view with includePreview=true

"Create a Core Data model called Task with title, isDone, and dueDate"
→ Uses scaffold_coredata_model with custom attributes

Analysis

"Analyze this IPA file — what's the bundle ID, size, and architectures?"
→ Uses ipa_analyze to unzip and inspect

"Check what privacy permissions this IPA requires"
→ Uses ipa_permissions to list NS*UsageDescription keys

"Verify that my dSYM file matches the release binary"
→ Uses dsym_verify to compare UUIDs

Prompt Cookbook

Ready-to-use prompts for common iOS development workflows:

Full build-test-deploy cycle

Build my project with the Release configuration, run all tests on an iPhone 16 Pro
simulator, and if tests pass, create an archive. Show me the test results.

Simulator setup from scratch

List available iOS runtimes, create a new iPhone 16 simulator with the latest iOS,
boot it, and open the Simulator app so I can see it.

Debug a crash

Stream the simulator logs for 30 seconds while I reproduce the crash.
Filter for error-level messages from my app's bundle ID com.myteam.myapp.

App Store screenshot preparation

Boot the simulator, set the status bar to 9:41 with full battery and full wifi
signal, set carrier name to an empty string, then take a screenshot.

CI/CD validation

Clean the project, build with Release configuration, run all tests,
check SwiftLint violations, and verify the binary size of the built product.

Dependency audit

Show me the full SPM dependency tree, then check if any CocoaPods are outdated.
Also run SwiftLint to check code quality.

New feature scaffolding

Create a SwiftUI view called ProfileView, a corresponding ProfileViewModel,
and a Core Data model called UserProfile with fields: id (UUID), name (String),
email (String), avatarURL (String), and lastLogin (Date).

Physical device deployment

List connected physical devices, install my built app on the first device,
launch it, and stream the device console logs for 20 seconds.

Tool Reference

Build & Compile (8 tools)

| Tool | Description | Key Parameters | | ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | xcode_build | Build project/workspace | scheme (req), projectPath, configuration, destination, sdk, derivedDataPath, extraArgs | | xcode_clean | Clean build artifacts | scheme (req), projectPath | | xcode_archive | Create archive for distribution | scheme (req), archivePath (req), projectPath, configuration | | xcode_export | Export IPA from archive | archivePath (req), exportPath (req), exportOptionsPlist (req) | | xcode_test | Run unit and UI tests | scheme (req), destination (req), projectPath, testPlan, onlyTesting, skipTesting | | xcode_test_without_building | Run tests without rebuilding | Same as xcode_test | | xcode_list | List schemes, targets, configurations | projectPath | | xcode_build_settings | Show resolved build settings | projectPath, scheme, configuration |

Simulator Management (10 tools)

| Tool | Description | Key Parameters | | ----------------------------- | --------------------------------------- | ----------------------------------------------------- | | simulator_list | List all simulators with state | state (filter: "Booted", "Shutdown") | | simulator_create | Create new simulator | name (req), deviceTypeId (req), runtimeId (req) | | simulator_boot | Boot a simulator | deviceId (req) | | simulator_shutdown | Shutdown simulator(s) | deviceId (default: "all") | | simulator_delete | Delete a simulator | deviceId (req, or "unavailable") | | simulator_erase | Erase all content and settings | deviceId (req) | | simulator_open | Open Simulator.app for a device | deviceId (req) | | simulator_list_runtimes | List iOS/watchOS/tvOS/visionOS runtimes | — | | simulator_list_device_types | List device types (iPhone, iPad, etc.) | — | | simulator_clone | Clone an existing simulator | deviceId (req), newName (req) |

App Lifecycle (8 tools)

| Tool | Description | Key Parameters | | ------------------- | ------------------------------ | ----------------------------------------------------------------------- | | app_install | Install .app on simulator | deviceId (req), appPath (req) | | app_uninstall | Uninstall by bundle ID | deviceId (req), bundleId (req) | | app_launch | Launch app by bundle ID | deviceId (req), bundleId (req), args, consolePty | | app_terminate | Terminate running app | deviceId (req), bundleId (req) | | app_get_container | Get app container path | deviceId (req), bundleId (req), container ("app"/"data"/"groups") | | app_list | List installed apps | deviceId (req) | | app_open_url | Open URL for deep link testing | deviceId (req), url (req) | | app_privacy | Grant/revoke/reset permissions | deviceId (req), action (req), service (req), bundleId |

all, calendar, contacts-limited, contacts, location, location-always, photos-add, photos, media-library, microphone, motion, reminders, siri, speech-recognition, camera, faceid, health, homekit, usertracking

Debugging & Logging (7 tools)

| Tool | Description | Key Parameters | | --------------------- | ----------------------------------- | ---------------------------------------------------------------- | | log_stream | Stream live logs for N seconds | deviceId (req), predicate, level, timeout (default: 10s) | | log_collect | Collect recent logs | deviceId (req), predicate, last ("5m", "1h"), style | | screenshot | Capture screenshot as PNG | deviceId (req), outputPath (auto-generated if omitted) | | screen_record | Record screen as MP4 | deviceId (req), outputPath, duration (default: 10s) | | diagnostics | Collect diagnostic report | outputPath | | accessibility_audit | Run accessibility audit (Xcode 15+) | deviceId (req) | | device_appearance | Set light/dark mode | deviceId (req), appearance ("light"/"dark") |

subsystem == "com.example.app"
eventMessage contains "error"
subsystem == "com.example.app" AND messageType == error
process == "MyApp"

Simulator Environment (6 tools)

| Tool | Description | Key Parameters | | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | location_set | Set GPS coordinates | deviceId (req), latitude (req), longitude (req) | | location_clear | Clear simulated location | deviceId (req) | | push_notification | Send push via APNs JSON payload | deviceId (req), bundleId (req), payload (req, JSON string) | | status_bar_override | Override status bar | deviceId (req), time, batteryLevel, batteryState, wifiBars, cellularBars, operatorName, dataNetwork | | status_bar_clear | Reset status bar to defaults | deviceId (req) | | keyboard_input | Send text input to simulator | deviceId (req), text (req) |

{
  "aps": {
    "alert": {
      "title": "New Message",
      "body": "You have a new message from John"
    },
    "badge": 1,
    "sound": "default"
  },
  "customKey": "customValue"
}

Code Signing & Provisioning (5 tools)

| Tool | Description | Key Parameters | | ----------------------- | ------------------------------------ | ------------------- | | signing_identities | List code signing identities | — | | provisioning_profiles | List installed profiles with details | — | | profile_inspect | Decode and inspect a profile | profilePath (req) | | keychain_list | List keychains | — | | entitlements_check | Show entitlements of built app | appPath (req) |

Package Management (6 tools)

| Tool | Description | Key Parameters | | ----------------------- | ----------------------------- | -------------------------------------------------- | | spm_resolve | Resolve SPM dependencies | projectPath, scheme, clonedSourcePackagesDir | | spm_update | Update SPM packages | projectPath | | spm_show_dependencies | Show dependency tree as JSON | projectPath | | pod_install | Run CocoaPods install | projectPath, repoUpdate | | pod_update | Update pods (all or specific) | projectPath, podName | | pod_outdated | Check outdated pods | projectPath |

Project Scaffolding (5 tools)

| Tool | Description | Key Parameters | | ------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | project_create | Create new Xcode project | name (req), template ("swiftui"/"uikit"), platform ("ios"/"macos"/"multiplatform"), outputPath (req), bundleId, organizationName, minimumDeploymentTarget | | scaffold_view | Generate SwiftUI View | name (req), outputPath (req), includePreview (default: true) | | scaffold_viewmodel | Generate @Observable ViewModel | name (req), outputPath (req) | | scaffold_coredata_model | Generate Core Data model | name (req), outputPath (req), attributes (array of {name, type}) | | scaffold_widget | Generate WidgetKit extension | name (req), outputPath (req), kind ("static"/"configurable") |

String, Integer16, Integer32, Integer64, Double, Float, Boolean, Date, Binary, UUID, URI

IPA & App Analysis (4 tools)

| Tool | Description | Key Parameters | | ----------------- | -------------------------------------------------------- | ------------------------------------ | | ipa_analyze | Inspect IPA: size, Info.plist, architectures, frameworks | ipaPath (req) | | ipa_permissions | List privacy usage descriptions | ipaPath (req) | | binary_size | Analyze Mach-O binary size by segment | binaryPath (req) | | dsym_verify | Verify dSYM matches binary UUID | dsymPath (req), binaryPath (req) |

Code Quality (4 tools)

| Tool | Description | Key Parameters | | ------------------ | ------------------------------------ | ----------------------------------------- | | swiftlint_run | Run SwiftLint analysis (JSON output) | path, config | | swiftlint_fix | Auto-fix SwiftLint violations | path, config | | swift_format_run | Run swift-format lint | path (req), recursive (default: true) | | build_warnings | Extract warnings from build log | projectPath, derivedDataPath |

Physical Devices (4 tools)

| Tool | Description | Key Parameters | | ------------------------- | -------------------------------------- | ------------------------------------------ | | physical_device_list | List connected iOS devices (Xcode 15+) | — | | physical_device_install | Install app on device | deviceId (req), appPath (req) | | physical_device_launch | Launch app on device | deviceId (req), bundleId (req) | | physical_device_console | Stream device console logs | deviceId (req), timeout (default: 10s) |

Architecture

src/
├── index.ts              # MCP server entry point, registers all 11 tool categories
├── types.ts              # Environment, ExecResult, ExecOptions interfaces
├── executor.ts           # Shell command execution (execFile, spawn, stdin piping)
├── environment.ts        # Xcode environment detection (xcode-select, xcrun, simctl, devicectl)
├── utils/
│   ├── response.ts       # textResponse, errorResponse, execResultResponse, withErrorHandling
│   ├── validation.ts     # Path, bundle ID, and name validation
│   └── logger.ts         # Structured stderr logging (stdout reserved for MCP protocol)
├── tools/
│   ├── build/            # 8 tools — xcodebuild build, clean, archive, export, test
│   ├── simulator/        # 10 tools — xcrun simctl create, boot, shutdown, list, clone
│   ├── app/              # 8 tools — install, launch, terminate, privacy, openurl
│   ├── debug/            # 7 tools — log stream/collect, screenshot, screen record
│   ├── environment/      # 6 tools — location, push notifications, status bar
│   ├── signing/          # 5 tools — identities, profiles, entitlements
│   ├── packages/         # 6 tools — SPM resolve/update, pod install/update
│   ├── scaffold/         # 5 tools — project creation, view/viewmodel/widget generation
│   ├── analyze/          # 4 tools — IPA analysis, binary size, dSYM verification
│   ├── quality/          # 4 tools — SwiftLint, swift-format, build warnings
│   └── device/           # 4 tools — physical device list, install, launch, console
└── templates/            # Swift project and component templates
    ├── SwiftUIView.swift.template
    ├── ViewModel.swift.template
    ├── CoreDataModel.swift.template
    └── Widget.swift.template

tests/                    # 112 tests across 15 test files
├── executor.test.ts
├── environment.test.ts
├── utils/
│   ├── response.test.ts
│   └── validation.test.ts
└── tools/                # One test file per tool category

Design Principles

• One handler per tool — each tool is a single async function in its own file
• Zod validation — all input parameters validated at the MCP registration layer
• JSON-first — prefers -j flag for JSON output from simctl commands
• Graceful errors — actionable error messages (e.g., "Is the simulator booted?")
• Response truncation — long outputs (>100KB) are truncated to prevent protocol overflows
• Timeout management — configurable per-tool (builds get 600s, quick queries get 30s)
• No Xcode required at install — environment detection happens at runtime

Development

Setup

git clone https://github.com/sitharaj88/xcode-pilot-mcp.git
cd xcode-pilot-mcp
npm install

Build

npm run build        # Compile TypeScript + copy templates + chmod +x
npm run dev          # Watch mode (tsc --watch)

Test

npm test             # Run all tests
npm run test:coverage  # Run with coverage report

Code Quality

npm run lint         # ESLint
npm run lint:fix     # ESLint with auto-fix
npm run format       # Prettier write
npm run format:check # Prettier check only
npm run typecheck    # TypeScript --noEmit
npm run check        # All of the above

Scripts Reference

| Script | Description | | ---------------- | ------------------------------------------- | | build | Compile TS, copy templates, make executable | | dev | TypeScript watch mode | | test | Run vitest | | test:coverage | Run vitest with V8 coverage | | lint | ESLint check | | lint:fix | ESLint auto-fix | | format | Prettier write | | format:check | Prettier check | | typecheck | TypeScript type check | | check | typecheck + lint + format:check | | prepare | Husky git hooks setup | | prepublishOnly | Full quality gate before npm publish |

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR guidelines.

License

MIT — Sitharaj Seenivasan