{
  "markdown": "# Preflight MCP\n\nThe 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.\n\n**82 tools** across 14 categories. Zero cursor interference — works silently in the background while you use your Mac.\n\nInspired by [Playwright MCP](https://github.com/anthropics/mcp-server-playwright) for web automation — Preflight brings the same structured accessibility-first approach to iOS.\n\n[![npm version](https://img.shields.io/npm/v/preflight-ios-mcp)](https://www.npmjs.com/package/preflight-ios-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Why Preflight?\n\n- **No disk clutter** — Screenshots and video frames return directly in chat. No folders filling up.\n- **AI-optimized** — Images compressed for minimal token usage. Video → key frames (most AI models can't view video files).\n- **Accessibility-first** — Like Playwright's `browser_snapshot`, use `simulator_snapshot` to understand the screen without vision models.\n- **Cursor-free** — Touch injection via idb (IndigoHID) — your Mac cursor stays put.\n- **82 tools** — From basic tap/swipe to StoreKit testing, network conditioning, memory profiling, and crash log analysis.\n\n## Quick Start\n\n### Prerequisites\n\n- macOS with Xcode and iOS Simulator installed\n- Node.js 18+\n- [Facebook idb](https://fbidb.io/) (recommended for cursor-free operation)\n\n### Install idb (recommended)\n\n```bash\nbrew tap facebook/fb\nbrew install idb-companion\npip3 install fb-idb\n```\n\n> Without idb, the server falls back to CGEvent mouse injection (works but briefly moves your cursor).\n\n### Install via npm (recommended)\n\n```bash\nnpm install -g preflight-ios-mcp\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/EthanAckerman-git/Preflight.git\ncd Preflight\nnpm install\nnpm run build\n```\n\n## Setup by IDE / AI Tool\n\n> Add your Python bin directory to `PATH` if idb was installed via pip (e.g., `~/Library/Python/3.x/bin`).\n\n### Claude Code\n\n```bash\nclaude mcp add preflight -- npx preflight-ios-mcp\n```\n\nOr add to **.mcp.json** in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"preflight\": {\n      \"command\": \"npx\",\n      \"args\": [\"preflight-ios-mcp\"],\n      \"env\": {\n        \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to **~/.cursor/mcp.json** (global) or **.cursor/mcp.json** (per-project):\n\n```json\n{\n  \"mcpServers\": {\n    \"preflight\": {\n      \"command\": \"npx\",\n      \"args\": [\"preflight-ios-mcp\"],\n      \"env\": {\n        \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\nThen in Cursor: **Settings → MCP** — verify \"preflight\" shows as connected.\n\n### Windsurf\n\nAdd to **~/.codeium/windsurf/mcp_config.json**:\n\n```json\n{\n  \"mcpServers\": {\n    \"preflight\": {\n      \"command\": \"npx\",\n      \"args\": [\"preflight-ios-mcp\"],\n      \"env\": {\n        \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\nThen in Windsurf: **Settings → Cascade → MCP** — verify \"preflight\" appears.\n\n### VS Code (Copilot / Cline / Continue)\n\nAdd to **.vscode/mcp.json** in your project:\n\n```json\n{\n  \"servers\": {\n    \"preflight\": {\n      \"command\": \"npx\",\n      \"args\": [\"preflight-ios-mcp\"],\n      \"env\": {\n        \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\nFor **Cline** (VS Code extension), add to **~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json**:\n\n```json\n{\n  \"mcpServers\": {\n    \"preflight\": {\n      \"command\": \"npx\",\n      \"args\": [\"preflight-ios-mcp\"],\n      \"env\": {\n        \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\n### Zed\n\nAdd to **~/.config/zed/settings.json**:\n\n```json\n{\n  \"context_servers\": {\n    \"preflight\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"preflight-ios-mcp\"],\n        \"env\": {\n          \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Any MCP-Compatible Client\n\nPreflight uses the standard MCP stdio transport. Configure your client to run:\n\n```bash\nnpx preflight-ios-mcp\n```\n\nSet the `PATH` environment variable to include idb's location for cursor-free touch injection.\n\n## Tools Reference\n\n### Observation (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_screenshot` | Take a JPEG screenshot optimized for AI chat (~200-400KB). Returns image inline. |\n| `simulator_list_devices` | List simulators with name, UDID, state, runtime. Filter: `booted`, `available`, `all`. |\n| `simulator_list_apps` | List installed apps with bundle IDs. Toggle `includeSystem` for system apps. |\n| `simulator_app_info` | Get app metadata: name, version, bundle path, data path, type. |\n| `simulator_get_clipboard` | Read the simulator's clipboard text. |\n| `simulator_get_screen_info` | Window geometry, coordinate mapping, scale factor. Debug tap accuracy. |\n\n### User Interaction (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_tap` | Tap at (x, y) in simulator screen points. Cursor-free via idb. |\n| `simulator_swipe` | Swipe between two points. Supports edge-swipe-back from x=1. |\n| `simulator_long_press` | Long press with configurable duration. Context menus, drag initiation. |\n| `simulator_type_text` | Type text into the focused field. |\n| `simulator_press_key` | Press special keys (return, escape, arrows, F-keys) with modifiers. |\n| `simulator_navigate_back` | Navigate back via Cmd+[. Workaround for edge-swipe limitations. |\n\n### Playwright-Inspired (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_snapshot` | **Preferred over screenshots.** Structured accessibility tree — roles, labels, values, positions. No vision model needed. Like Playwright's `browser_snapshot`. |\n| `simulator_wait_for_element` | Wait for an element to appear (by label, role, or text). Polls with configurable timeout. Like Playwright's `browser_wait_for`. |\n| `simulator_element_exists` | Quick boolean check: does an element matching criteria exist on screen right now? |\n\n### Device Management (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_boot` | Boot a device by name or UDID. Optional `waitForBoot` polling. |\n| `simulator_shutdown` | Shut down a running simulator. |\n| `simulator_erase` | Factory reset — erases all content and settings. |\n| `simulator_open_url` | Open URLs or deep links (e.g., `myapp://screen`). |\n| `simulator_open_simulator` | Open the Simulator.app application. |\n| `simulator_get_booted_sim_id` | Get the UDID of the currently booted simulator. |\n\n### App Management (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_launch_app` | Launch by bundle ID with optional args and env vars. |\n| `simulator_terminate_app` | Force-terminate a running app. |\n| `simulator_install_app` | Install a .app bundle or .ipa from a local path. |\n| `simulator_uninstall_app` | Uninstall by bundle ID. |\n\n### Debugging & Diagnostics (9 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_get_logs` | Query device logs. Filter by process, subsystem, level, time range, message content. |\n| `simulator_stream_logs` | Live log streaming with start/read/stop lifecycle. Configurable buffer. |\n| `simulator_get_app_container` | Get filesystem path to app's bundle, data, or shared group container. |\n| `simulator_list_app_files` | Browse an app's Documents/, Library/, Caches/, tmp/ directories. |\n| `simulator_read_app_file` | Read plists (→JSON), SQLite (→schema), and text files from app data. |\n| `simulator_get_crash_logs` | Retrieve crash reports with stack traces and thread states. |\n| `simulator_diagnose` | Xcode version, disk usage, booted devices, system info. |\n| `simulator_accessibility_audit` | Full iOS accessibility tree — real UIButton/UILabel elements with labels, frames, roles. |\n| `simulator_describe_point` | Returns the accessibility element at given coordinates. |\n\n### System Simulation (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_set_location` | Set GPS coordinates (lat/lng). Test location-based features. |\n| `simulator_send_push` | Send push notifications with full APNs payload JSON. |\n| `simulator_set_clipboard` | Set the simulator clipboard text. |\n| `simulator_add_media` | Add photos/videos to the camera roll from local files. |\n| `simulator_grant_permission` | Grant, revoke, or reset permissions (camera, location, photos, contacts, microphone, etc.). |\n\n### UI Configuration (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_set_appearance` | Switch between light and dark mode. |\n| `simulator_override_status_bar` | Set time, battery, signal, carrier, network type. |\n| `simulator_record_video` | Start screen recording. On stop, key frames are extracted as images for AI chat. |\n| `simulator_stop_recording` | Stop recording. Returns key frames inline (no disk clutter). Optional `savePath` to keep the video. |\n\n### Advanced Debugging & Testing (18 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_set_content_size` | Set Dynamic Type preferred size (13 categories from extra-small to accessibility-XXXL). |\n| `simulator_set_increase_contrast` | Toggle Increase Contrast accessibility setting. |\n| `simulator_location_scenario` | Run predefined GPS routes: Freeway Drive, City Run, City Bicycle Ride. |\n| `simulator_location_route` | Simulate movement along custom waypoints with configurable speed. |\n| `simulator_memory_warning` | Trigger simulated memory warning (didReceiveMemoryWarning). |\n| `simulator_keychain` | Add root certificates, add certificates, or reset the device keychain. |\n| `simulator_icloud_sync` | Trigger iCloud synchronization on the device. |\n| `simulator_verbose_logging` | Enable/disable verbose device logging for deep debugging. |\n| `simulator_install_app_data` | Install .xcappdata packages to restore test data snapshots. |\n| `simulator_get_env` | Read environment variables from the running simulator. |\n| `simulator_biometric` | Enroll, unenroll, match, or fail Face ID / Touch ID for auth testing. |\n| `simulator_network_status` | Get network configuration — DNS, interfaces, connectivity status. |\n| `simulator_defaults_read` | Read UserDefaults from inside the simulator (inspect app prefs, feature flags). |\n| `simulator_defaults_write` | Write UserDefaults inside the simulator (set flags, inject test config). |\n| `simulator_rotate` | Rotate the simulator left or right. |\n| `simulator_notify_post` | Post a Darwin notification to trigger system events. |\n| `simulator_set_locale` | Set device locale for internationalization testing. |\n| `simulator_trigger_siri` | Invoke Siri for voice command testing. |\n\n### Accessibility Settings (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_set_reduce_motion` | Toggle Reduce Motion accessibility setting (via defaults write + notification). |\n| `simulator_set_smart_invert` | Toggle Smart Invert Colors (via defaults write + notification). |\n| `simulator_set_bold_text` | Toggle Bold Text (via defaults write + notification). |\n| `simulator_set_reduce_transparency` | Toggle Reduce Transparency (via defaults write + notification). |\n\n### Device Creation & Management (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_create_device` | Create a new simulator with device type and runtime. |\n| `simulator_delete_device` | Permanently delete a simulator device. |\n| `simulator_rename_device` | Rename an existing device. |\n| `simulator_clone_device` | Clone a device with all its state. |\n\n### StoreKit Testing (6 tools) — Xcode 14-16\n\n| Tool | Description |\n|------|-------------|\n| `simulator_storekit_config` | Enable or disable StoreKit test mode. |\n| `simulator_storekit_transactions` | List all StoreKit test transactions. |\n| `simulator_storekit_delete_transactions` | Clear all test transactions. |\n| `simulator_storekit_manage_subscription` | Expire or force-renew a subscription. |\n| `simulator_storekit_manage_transaction` | Refund, approve, or decline ask-to-buy transactions. |\n| `simulator_storekit_reset_eligibility` | Reset introductory offer eligibility for all products. |\n\n### Network Testing (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_network_condition` | Apply network throttling with presets (3G, LTE, Edge, WiFi, 100% loss) or custom bandwidth/latency/loss. |\n| `simulator_network_capture` | Capture network activity summary — active connections, DNS, interfaces. |\n\n### Debugging & Profiling (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `simulator_leak_check` | Check a running app for memory leaks via Apple's `leaks` tool. |\n| `simulator_heap_info` | Dump heap allocation summary — object counts by class, total memory. |\n| `simulator_vmmap` | Show virtual memory map — regions, sizes, permissions. |\n| `simulator_sample_process` | Sample a process for CPU hotspot detection and hang analysis. |\n| `simulator_thermal_state` | Simulate thermal pressure state changes (nominal, fair, serious, critical). |\n\n## Architecture\n\n```\nsrc/\n├── index.ts                    # MCP server entry, 82 tool registrations\n├── helpers/\n│   ├── idb.ts                  # Facebook idb CLI wrapper (cursor-free touch)\n│   ├── simctl.ts               # xcrun simctl command wrapper\n│   ├── applescript.ts          # Keyboard input + CGEvent fallback\n│   ├── coordinate-mapper.ts    # Simulator points → macOS screen coords\n│   ├── mouse-events.swift      # Native Swift CGEvent binary (fallback)\n│   └── logger.ts               # Structured stderr logging\n└── tools/\n    ├── screenshot.ts           # JPEG capture optimized for AI chat\n    ├── interaction.ts          # Tap, swipe, long press, type, key\n    ├── device.ts               # Boot, shutdown, erase, open URL\n    ├── app.ts                  # Install, launch, terminate, list\n    ├── system.ts               # Location, push, clipboard, media, permissions\n    ├── ui.ts                   # Appearance, status bar, video recording, navigate back\n    ├── debug.ts                # Logs, files, crash reports, accessibility\n    ├── advanced.ts             # Dynamic Type, keychain, iCloud, biometric, defaults, accessibility, rotation, locale\n    ├── storekit.ts             # StoreKit testing — transactions, subscriptions, eligibility\n    ├── network.ts              # Network conditioning (dnctl/pfctl) and capture\n    ├── profiling.ts            # Memory profiling — leaks, heap, vmmap, sample, thermal\n    └── playwright.ts           # Snapshot, wait_for_element, element_exists\n```\n\n### Design Philosophy\n\n**Accessibility-first, like Playwright MCP:**\n1. Use `simulator_snapshot` to understand the screen (structured text, no vision model)\n2. Use coordinates from the snapshot to `simulator_tap`, `simulator_swipe`, etc.\n3. Use `simulator_screenshot` when you need visual verification\n4. Use `simulator_wait_for_element` before interacting with elements that appear after transitions\n\n**No disk clutter:**\n- Screenshots return as base64 in chat — no folders filling up your Desktop\n- Video recordings extract key frames as inline images on stop\n- Optional `savePath` parameter if you actually need files on disk\n\n### Touch Injection Pipeline\n\n```\nsimulator_tap(x=200, y=400)\n    │\n    ├─ idb available? ──YES──► idb ui tap --udid <UDID> 200 400\n    │                           (IndigoHID → real iOS touch event)\n    │                           (zero cursor movement)\n    │\n    └─ idb unavailable? ──► coordinate mapper → macOS screen coords\n                             → Swift CGEvent binary → mouse down/up\n```\n\n## Demo App\n\nA SwiftUI demo app is included in `demo-app/` for testing all MCP features:\n\n```bash\ncd demo-app\nxcodebuild -project MCPDemo.xcodeproj -scheme MCPDemo \\\n  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \\\n  build\n```\n\nThe demo app has 7 tabs exercising every tool category:\n- **Interactions**: Buttons, text fields, long-press zones, navigation stack, scrollable lists\n- **Location**: Live GPS display for testing `simulator_set_location`\n- **Notifications**: Push notification display for testing `simulator_send_push`\n- **Settings**: Clipboard, file I/O, accessibility toggles, UserDefaults\n- **StoreKit**: Mock purchases and subscriptions for testing StoreKit tools\n- **Network**: Connection monitoring and latency testing for network conditioning\n- **Debug**: Memory/CPU stress tests, thermal state, accessibility settings observer, biometric auth\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `LOG_LEVEL` | `info` | Logging level: `debug`, `info`, `warn`, `error` |\n| `PREFLIGHT_FILTERED_TOOLS` | (none) | Comma-separated list of tool names to disable |\n| `PREFLIGHT_IDB_PATH` | (auto-detect) | Custom path to idb binary |\n| `PATH` | System PATH | Must include idb binary location |\n\n## Example Prompts\n\n### QA Testing\n> \"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.\"\n\n### Accessibility-First Workflow (Playwright-style)\n> \"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.\"\n\n### Debugging\n> \"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.\"\n\n### Dark Mode Testing\n> \"Switch to dark mode, take a screenshot, then switch to light mode and screenshot again.\"\n\n## Troubleshooting\n\n### idb not detected\nIf tools show `[CGEvent fallback]` instead of `[cursor-free]`:\n\n1. Verify idb is installed: `which idb` or check `~/Library/Python/3.x/bin/idb`\n2. Add the idb path to your MCP config's `PATH` env var\n3. Or set `PREFLIGHT_IDB_PATH` directly\n\n### Simulator not found\n1. Open Simulator.app: `open -a Simulator`\n2. Boot a device: use `simulator_boot` or `xcrun simctl boot \"iPhone 16 Pro\"`\n\n### Accessibility permission errors\n1. Go to System Settings → Privacy & Security → Accessibility\n2. Add your terminal app (Terminal.app, iTerm, Claude Code, Cursor, Windsurf, etc.)\n\n## Development\n\n```bash\nnpm run dev    # Watch mode (TypeScript only)\nnpm run build  # Full rebuild (TypeScript + Swift binary)\nnode dist/index.js  # Run directly\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n",
  "bytes": 18774,
  "sha": "4c27b27ba0bbd86de03ed97d0505a974bb51a107afffd0e311b6b22fffc4478d",
  "repo_slug": "ethanackerman-git/preflight",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ethanackerman_git_preflight_io_2f96f808/readme"
}