Preflight MCP Server

Preflight MCP

The most comprehensive MCP (Model Context Protocol) server for iOS Simulator automation. Gives AI agents like Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible tool full control over iOS Simulators — tap, swipe, type, read accessibility trees, inspect app data, capture screenshots, record video, manage devices, and debug apps in real time.

82 tools across 14 categories. Zero cursor interference — works silently in the background while you use your Mac.

Inspired by Playwright MCP for web automation — Preflight brings the same structured accessibility-first approach to iOS.

Why Preflight?

• No disk clutter — Screenshots and video frames return directly in chat. No folders filling up.
• AI-optimized — Images compressed for minimal token usage. Video → key frames (most AI models can't view video files).
• Accessibility-first — Like Playwright's browser_snapshot, use simulator_snapshot to understand the screen without vision models.
• Cursor-free — Touch injection via idb (IndigoHID) — your Mac cursor stays put.
• 82 tools — From basic tap/swipe to StoreKit testing, network conditioning, memory profiling, and crash log analysis.

Quick Start

Prerequisites

• macOS with Xcode and iOS Simulator installed
• Node.js 18+
• Facebook idb (recommended for cursor-free operation)

Install idb (recommended)

brew tap facebook/fb
brew install idb-companion
pip3 install fb-idb

Without idb, the server falls back to CGEvent mouse injection (works but briefly moves your cursor).

Install via npm (recommended)

npm install -g preflight-ios-mcp

Build from Source

git clone https://github.com/EthanAckerman-git/Preflight.git
cd Preflight
npm install
npm run build

Setup by IDE / AI Tool

Add your Python bin directory to PATH if idb was installed via pip (e.g., ~/Library/Python/3.x/bin).

Claude Code

claude mcp add preflight -- npx preflight-ios-mcp

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Then in Cursor: Settings → MCP — verify "preflight" shows as connected.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Then in Windsurf: Settings → Cascade → MCP — verify "preflight" appears.

VS Code (Copilot / Cline / Continue)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

For Cline (VS Code extension), add to ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["preflight-ios-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "preflight": {
      "command": {
        "path": "npx",
        "args": ["preflight-ios-mcp"],
        "env": {
          "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
        }
      }
    }
  }
}

Any MCP-Compatible Client

Preflight uses the standard MCP stdio transport. Configure your client to run:

npx preflight-ios-mcp

Set the PATH environment variable to include idb's location for cursor-free touch injection.

Tools Reference

Observation (6 tools)

User Interaction (6 tools)

Playwright-Inspired (3 tools)

Device Management (6 tools)

App Management (4 tools)

Debugging & Diagnostics (9 tools)

System Simulation (5 tools)

UI Configuration (4 tools)

Advanced Debugging & Testing (18 tools)

Accessibility Settings (4 tools)

Device Creation & Management (4 tools)

StoreKit Testing (6 tools) — Xcode 14-16

Network Testing (2 tools)

Debugging & Profiling (5 tools)

Architecture

src/
├── index.ts                    # MCP server entry, 82 tool registrations
├── helpers/
│   ├── idb.ts                  # Facebook idb CLI wrapper (cursor-free touch)
│   ├── simctl.ts               # xcrun simctl command wrapper
│   ├── applescript.ts          # Keyboard input + CGEvent fallback
│   ├── coordinate-mapper.ts    # Simulator points → macOS screen coords
│   ├── mouse-events.swift      # Native Swift CGEvent binary (fallback)
│   └── logger.ts               # Structured stderr logging
└── tools/
    ├── screenshot.ts           # JPEG capture optimized for AI chat
    ├── interaction.ts          # Tap, swipe, long press, type, key
    ├── device.ts               # Boot, shutdown, erase, open URL
    ├── app.ts                  # Install, launch, terminate, list
    ├── system.ts               # Location, push, clipboard, media, permissions
    ├── ui.ts                   # Appearance, status bar, video recording, navigate back
    ├── debug.ts                # Logs, files, crash reports, accessibility
    ├── advanced.ts             # Dynamic Type, keychain, iCloud, biometric, defaults, accessibility, rotation, locale
    ├── storekit.ts             # StoreKit testing — transactions, subscriptions, eligibility
    ├── network.ts              # Network conditioning (dnctl/pfctl) and capture
    ├── profiling.ts            # Memory profiling — leaks, heap, vmmap, sample, thermal
    └── playwright.ts           # Snapshot, wait_for_element, element_exists

Design Philosophy

Accessibility-first, like Playwright MCP:

1. Use simulator_snapshot to understand the screen (structured text, no vision model)
2. Use coordinates from the snapshot to simulator_tap, simulator_swipe, etc.
3. Use simulator_screenshot when you need visual verification
4. Use simulator_wait_for_element before interacting with elements that appear after transitions

No disk clutter:

• Screenshots return as base64 in chat — no folders filling up your Desktop
• Video recordings extract key frames as inline images on stop
• Optional savePath parameter if you actually need files on disk

Touch Injection Pipeline

simulator_tap(x=200, y=400)
    │
    ├─ idb available? ──YES──► idb ui tap --udid <UDID> 200 400
    │                           (IndigoHID → real iOS touch event)
    │                           (zero cursor movement)
    │
    └─ idb unavailable? ──► coordinate mapper → macOS screen coords
                             → Swift CGEvent binary → mouse down/up

Demo App

A SwiftUI demo app is included in demo-app/ for testing all MCP features:

cd demo-app
xcodebuild -project MCPDemo.xcodeproj -scheme MCPDemo \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  build

The demo app has 7 tabs exercising every tool category:

• Interactions: Buttons, text fields, long-press zones, navigation stack, scrollable lists
• Location: Live GPS display for testing simulator_set_location
• Notifications: Push notification display for testing simulator_send_push
• Settings: Clipboard, file I/O, accessibility toggles, UserDefaults
• StoreKit: Mock purchases and subscriptions for testing StoreKit tools
• Network: Connection monitoring and latency testing for network conditioning
• Debug: Memory/CPU stress tests, thermal state, accessibility settings observer, biometric auth

Configuration

Environment Variables

Example Prompts

QA Testing

"Boot the iPhone 16 Pro simulator, install my app at ./build/MyApp.app, launch it, and take a screenshot of the home screen. Then tap the login button, type test@email.com in the email field, and verify the form validation works."

Accessibility-First Workflow (Playwright-style)

"Take a snapshot of the current screen to see what elements are available. Then tap the button labeled 'Sign In' and wait for the email text field to appear."

Debugging

"My app is crashing on launch. Check the crash logs for MyApp, then get the last 5 minutes of device logs filtered to the MyApp process."

Dark Mode Testing

"Switch to dark mode, take a screenshot, then switch to light mode and screenshot again."

Troubleshooting

idb not detected

If tools show [CGEvent fallback] instead of [cursor-free]:

1. Verify idb is installed: which idb or check ~/Library/Python/3.x/bin/idb
2. Add the idb path to your MCP config's PATH env var
3. Or set PREFLIGHT_IDB_PATH directly

Simulator not found

1. Open Simulator.app: open -a Simulator
2. Boot a device: use simulator_boot or xcrun simctl boot "iPhone 16 Pro"

Accessibility permission errors

1. Go to System Settings → Privacy & Security → Accessibility
2. Add your terminal app (Terminal.app, iTerm, Claude Code, Cursor, Windsurf, etc.)

Development

npm run dev    # Watch mode (TypeScript only)
npm run build  # Full rebuild (TypeScript + Swift binary)
node dist/index.js  # Run directly

License

MIT License — see LICENSE for details.