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.

[Read the full documentation](https://sitharaj88.github.io/xcode-pilot-mcp/)

Table of Contents

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

Features

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)

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)

Simulator Management (10 tools)

App Lifecycle (8 tools)

<details> <summary><strong>Supported privacy services</strong></summary>

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

</details>

Debugging & Logging (7 tools)

<details> <summary><strong>Log predicate examples</strong></summary>

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

</details>

Simulator Environment (6 tools)

<details> <summary><strong>Push notification payload example</strong></summary>

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

</details>

Code Signing & Provisioning (5 tools)

Package Management (6 tools)

Project Scaffolding (5 tools)

<details> <summary><strong>Supported Core Data attribute types</strong></summary>

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

</details>

IPA & App Analysis (4 tools)

Code Quality (4 tools)

Physical Devices (4 tools)

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

Contributing

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

License

MIT — Sitharaj Seenivasan