preflight-ios-mcp

Preflight MCP

iOS シミュレーターの自動化に最も包括的な MCP（Model Context Protocol）サーバーです。Claude、ChatGPT、Cursor、Windsurf などの AI エージェントや、MCP 対応のあらゆるツールから iOS シミュレーターを完全に操作できます。タップ、スワイプ、文字入力、アクセシビリティツリーの読み取り、アプリデータの調査、スクリーンショットの撮影、動画の録画、デバイスの管理、アプリのリアルタイムデバッグに対応しています。

14 カテゴリーにわたる 82 個のツール を搭載しています。カーソルにまったく干渉せず、Mac を使っている間もバックグラウンドで静かに動作します。

Web 自動化向けの Playwright MCP に着想を得ており、Preflight は同じ構造化されたアクセシビリティ優先のアプローチを iOS にもたらします。

Preflight を選ぶ理由

• ディスクを散らかしません — スクリーンショットや動画のフレームはチャットに直接返されます。フォルダーが増えていくことはありません。
• AI に最適化 — 画像はトークン使用量を最小限に抑えるよう圧縮されます。動画はキーフレームに変換されます（ほとんどの AI モデルは動画ファイルを表示できません）。
• アクセシビリティ優先 — Playwright の browser_snapshot と同様に、simulator_snapshot を使えば、視覚モデルなしで画面の内容を把握できます。
• カーソル不要 — idb（IndigoHID）経由でタッチイベントを注入するため、Mac のカーソルはその場にとどまります。
• 82 個のツール — 基本的なタップやスワイプから、StoreKit テスト、ネットワーク状態の調整、メモリのプロファイリング、クラッシュログの分析まで対応します。

クイックスタート

前提条件

• Xcode と iOS Simulator がインストールされた macOS
• Node.js 18+
• Facebook idb（カーソルを動かさない操作に推奨）

idb をインストールする（推奨）

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

idb がない場合、サーバーは CGEvent によるマウスイベントの注入にフォールバックします（動作しますが、カーソルが一時的に動きます）。

npm 経由でインストールする（推奨）

npm install -g preflight-ios-mcp

ソースからビルドする

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

IDE／AI ツールごとのセットアップ

idb を pip 経由でインストールした場合は、Python の bin ディレクトリ（例：~/Library/Python/3.x/bin）を PATH に追加してください。

Claude Code

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

または、プロジェクトのルートにある .mcp.json に追加します。

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

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に追加します。

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

次に Cursor で Settings → MCP を開き、「preflight」が接続済みと表示されていることを確認します。

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

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

次に Windsurf で Settings → Cascade → MCP を開き、「preflight」が表示されていることを確認します。

VS Code（Copilot／Cline／Continue）

プロジェクトの .vscode/mcp.json に追加します。

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

Cline（VS Code 拡張機能）の場合は、~/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

~/.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"
        }
      }
    }
  }
}

MCP 対応クライアント全般

Preflight は標準の MCP stdio トランスポートを使用します。次のコマンドを実行するようクライアントを設定してください。

npx preflight-ios-mcp

カーソルを動かさないタッチイベントの注入に idb を使えるよう、PATH 環境変数に idb の場所を含めてください。

ツール一覧

観察（6 個のツール）

ツール	説明
simulator_screenshot	AI チャット向けに最適化された JPEG スクリーンショットを撮影します（約 200～400 KB）。画像をインラインで返します。
simulator_list_devices	名前、UDID、状態、ランタイムとともにシミュレーターを一覧表示します。booted、available、all で絞り込めます。
simulator_list_apps	インストール済みアプリをバンドル ID とともに一覧表示します。includeSystem を切り替えると、システムアプリも含められます。
simulator_app_info	名前、バージョン、バンドルパス、データパス、種類など、アプリのメタデータを取得します。
simulator_get_clipboard	シミュレーターのクリップボードにあるテキストを読み取ります。
simulator_get_screen_info	ウィンドウのジオメトリ、座標のマッピング、スケール係数を取得します。タップ精度のデバッグに使えます。

ユーザー操作（6 個のツール）

ツール	説明
simulator_tap	シミュレーター画面上の（x、y）をタップします。idb を使用するため、カーソルは表示されません。
simulator_swipe	2 点間をスワイプします。x=1 からのエッジスワイプによる戻る操作に対応しています。
simulator_long_press	指定可能な時間、長押しします。コンテキストメニューの表示やドラッグの開始に使用します。
simulator_type_text	フォーカス中のフィールドにテキストを入力します。
simulator_press_key	修飾キーを指定して、特殊キー（return、escape、矢印キー、F キー）を押します。
simulator_navigate_back	Cmd+[ で戻ります。エッジスワイプの制限に対する回避策です。

Playwright に着想を得たツール（3 個）

ツール	説明
simulator_snapshot	スクリーンショットより優先して使用してください。 ロール、ラベル、値、位置を含む構造化されたアクセシビリティツリーです。ビジョンモデルは不要です。Playwright の browser_snapshot に相当します。
simulator_wait_for_element	ラベル、ロール、テキストで指定した要素が表示されるまで待機します。タイムアウトは設定可能です。Playwright の browser_wait_for に相当します。
simulator_element_exists	条件に一致する要素が現在画面に存在するかをすばやく確認します。結果は真偽値です。

デバイス管理（6 個のツール）

ツール	説明
simulator_boot	名前または UDID を指定してデバイスを起動します。waitForBoot によるポーリングは任意です。
simulator_shutdown	起動中のシミュレーターをシャットダウンします。
simulator_erase	工場出荷時の状態にリセットし、すべてのコンテンツと設定を消去します。
simulator_open_url	URL またはディープリンク（例：myapp://screen）を開きます。
simulator_open_simulator	Simulator.app アプリケーションを開きます。
simulator_get_booted_sim_id	現在起動中のシミュレーターの UDID を取得します。

アプリ管理（4 個のツール）

ツール	説明
simulator_launch_app	バンドル ID を指定して起動します。引数と環境変数は任意で指定できます。
simulator_terminate_app	実行中のアプリを強制終了します。
simulator_install_app	ローカルパスから .app バンドルまたは .ipa をインストールします。
simulator_uninstall_app	バンドル ID を指定してアンインストールします。

デバッグと診断（9 個のツール）

ツール	説明
simulator_get_logs	デバイスのログを検索します。プロセス、サブシステム、レベル、時間範囲、メッセージ内容で絞り込めます。
simulator_stream_logs	開始／読み取り／停止のライフサイクルで、ログをリアルタイムにストリーミングします。バッファーは設定可能です。
simulator_get_app_container	アプリのバンドル、データ、または共有グループコンテナーのファイルシステムパスを取得します。
simulator_list_app_files	アプリの Documents/、Library/、Caches/、tmp/ ディレクトリを参照します。
simulator_read_app_file	アプリデータから plist（→JSON）、SQLite（→スキーマ）、テキストファイルを読み取ります。
simulator_get_crash_logs	スタックトレースとスレッド状態を含むクラッシュレポートを取得します。
simulator_diagnose	Xcode のバージョン、ディスク使用量、起動中のデバイス、システム情報を確認します。
simulator_accessibility_audit	ラベル、フレーム、ロールを備えた実際の UIButton／UILabel 要素を含む、iOS のアクセシビリティツリー全体を取得します。
simulator_describe_point	指定した座標にあるアクセシビリティ要素を返します。

システムシミュレーション（5 個のツール）

ツール	説明
simulator_set_location	GPS 座標（lat/lng）を設定します。位置情報を使用する機能のテストに使います。
simulator_send_push	APNs のペイロード JSON 全体を指定してプッシュ通知を送信します。
simulator_set_clipboard	シミュレーターのクリップボードテキストを設定します。
simulator_add_media	ローカルファイルから写真や動画をカメラロールに追加します。
simulator_grant_permission	権限（カメラ、位置情報、写真、連絡先、マイクなど）を許可、取り消し、またはリセットします。

UI 設定（4 個のツール）

ツール	説明
simulator_set_appearance	ライトモードとダークモードを切り替えます。
simulator_override_status_bar	時刻、バッテリー、電波、キャリア、ネットワークの種類を設定します。
simulator_record_video	画面録画を開始します。停止すると、キーフレームが画像として抽出され、AI チャットで利用できます。
simulator_stop_recording	録画を停止します。キーフレームをインラインで返します（ディスクを無駄に使いません）。動画を保存する場合は、オプションの savePath を指定します。

高度なデバッグとテスト（18 個のツール）

ツール	説明
simulator_set_content_size	Dynamic Type の優先サイズを設定します（極小からアクセシビリティ用 XXXL までの 13 段階）。
simulator_set_increase_contrast	アクセシビリティ設定「コントラストを上げる」を切り替えます。
simulator_location_scenario	定義済みの GPS ルート（高速道路のドライブ、市街地でのランニング、市街地でのサイクリング）を実行します。
simulator_location_route	速度を設定して、カスタムの経由地点に沿った移動をシミュレートします。
simulator_memory_warning	メモリ警告（didReceiveMemoryWarning）をシミュレートして発生させます。
simulator_keychain	ルート証明書の追加、証明書の追加、またはデバイスのキーチェーンのリセットを行います。
simulator_icloud_sync	デバイスで iCloud 同期を実行します。
simulator_verbose_logging	詳細なデバッグ用に、デバイスの詳細ログを有効または無効にします。
simulator_install_app_data	テストデータのスナップショットを復元するため、.xcappdata パッケージをインストールします。
simulator_get_env	実行中のシミュレーターから環境変数を読み取ります。
simulator_biometric	認証テスト用に、Face ID / Touch ID の登録、登録解除、一致、または失敗を実行します。
simulator_network_status	DNS、インターフェース、接続状況などのネットワーク設定を取得します。
simulator_defaults_read	シミュレーター内から UserDefaults を読み取ります（アプリの設定や機能フラグを確認します）。
simulator_defaults_write	シミュレーター内の UserDefaults に書き込みます（フラグの設定やテスト用設定の注入を行います）。
simulator_rotate	シミュレーターを左または右に回転させます。
simulator_notify_post	システムイベントを発生させるため、Darwin 通知を投稿します。
simulator_set_locale	国際化テスト用にデバイスのロケールを設定します。
simulator_trigger_siri	音声コマンドのテスト用に Siri を起動します。

アクセシビリティ設定（4 個のツール）

ツール	説明
simulator_set_reduce_motion	アクセシビリティ設定「視差効果を減らす」を切り替えます（defaults write と通知を使用）。
simulator_set_smart_invert	「反転（スマート）」を切り替えます（defaults write と通知を使用）。
simulator_set_bold_text	「文字を太くする」を切り替えます（defaults write と通知を使用）。
simulator_set_reduce_transparency	アクセシビリティ設定「透明度を下げる」を切り替えます（defaults write と通知を使用）。

デバイスの作成と管理（4 個のツール）

ツール	説明
simulator_create_device	デバイスの種類とランタイムを指定して、新しいシミュレーターを作成します。
simulator_delete_device	シミュレーターデバイスを完全に削除します。
simulator_rename_device	既存のデバイスの名前を変更します。
simulator_clone_device	すべての状態を含めてデバイスを複製します。

StoreKit テスト（6 個のツール）— Xcode 14-16

ツール	説明
simulator_storekit_config	StoreKit テストモードを有効または無効にします。
simulator_storekit_transactions	StoreKit のテストトランザクションをすべて一覧表示します。
simulator_storekit_delete_transactions	すべてのテストトランザクションを消去します。
simulator_storekit_manage_subscription	サブスクリプションを期限切れにするか、強制更新します。
simulator_storekit_manage_transaction	承認と購入のトランザクションを返金、承認、または拒否します。
simulator_storekit_reset_eligibility	すべての製品について、導入オファーの利用資格をリセットします。

ネットワークテスト（2 ツール）

ツール	説明
simulator_network_condition	プリセット（3G、LTE、Edge、WiFi、100% 損失）またはカスタムの帯域幅／レイテンシ／損失を指定して、ネットワークをスロットリングします。
simulator_network_capture	ネットワークアクティビティの概要（アクティブな接続、DNS、インターフェース）をキャプチャします。

デバッグとプロファイリング（5 ツール）

ツール	説明
simulator_leak_check	Apple の leaks ツールを使って、実行中のアプリのメモリリークを確認します。
simulator_heap_info	ヒープ割り当ての概要（クラスごとのオブジェクト数、合計メモリ）をダンプします。
simulator_vmmap	仮想メモリマップ（領域、サイズ、権限）を表示します。
simulator_sample_process	CPU ホットスポットの検出とハングの分析のため、プロセスをサンプリングします。
simulator_thermal_state	熱負荷状態の変化（nominal、fair、serious、critical）をシミュレートします。

アーキテクチャ

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

設計理念

Playwright MCP のように、アクセシビリティを最優先します：

1. simulator_snapshot を使って画面を把握します（構造化テキストを使用し、ビジョンモデルは不要です）
2. スナップショットの座標を使って simulator_tap、simulator_swipe などを実行します
3. 視覚的な確認が必要な場合は simulator_screenshot を使います
4. 画面遷移後に表示される要素を操作する前に simulator_wait_for_element を使います

ディスクを散らかしません：

• スクリーンショットはチャット内で Base64 として返されるため、デスクトップにフォルダーが増えません
• ビデオ録画は停止時に主要なフレームをインライン画像として抽出します
• ディスク上にファイルが必要な場合は、任意の savePath パラメーターを指定できます

タッチ注入パイプライン

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

デモアプリ

すべての MCP 機能をテストするための SwiftUI デモアプリが demo-app/ に含まれています：

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

デモアプリには、すべてのツールカテゴリを試せる 7 つのタブがあります：

• 操作：ボタン、テキストフィールド、長押し領域、ナビゲーションスタック、スクロール可能なリスト
• 位置情報：simulator_set_location のテスト用リアルタイム GPS 表示
• 通知：simulator_send_push のテスト用プッシュ通知表示
• 設定：クリップボード、ファイル I/O、アクセシビリティの切り替え、UserDefaults
• StoreKit：StoreKit ツールのテスト用モック購入とサブスクリプション
• ネットワーク：ネットワークコンディショニング用の接続監視とレイテンシテスト
• デバッグ：メモリ／CPU の負荷テスト、熱負荷状態、アクセシビリティ設定オブザーバー、生体認証

設定

環境変数

変数	デフォルト	説明
LOG_LEVEL	info	ログレベル：debug、info、warn、error
PREFLIGHT_FILTERED_TOOLS	（なし）	無効にするツール名をカンマ区切りで指定します
PREFLIGHT_IDB_PATH	（自動検出）	idb バイナリのカスタムパス
PATH	システムの PATH	idb バイナリの場所を含める必要があります

プロンプト例

QA テスト

「iPhone 16 Pro シミュレーターを起動し、./build/MyApp.app にあるアプリをインストールして起動し、ホーム画面のスクリーンショットを撮影してください。次に、ログインボタンをタップし、メールフィールドに [email protected] と入力して、フォームのバリデーションが機能することを確認してください。」

アクセシビリティ優先のワークフロー（Playwright 形式）

「現在の画面のスナップショットを撮って、利用可能な要素を確認してください。次に、「Sign In」というラベルのボタンをタップし、メールのテキストフィールドが表示されるまで待ってください。」

デバッグ

「アプリが起動時にクラッシュします。MyApp のクラッシュログを確認し、MyApp プロセスに絞り込んだ直近 5 分間のデバイスログを取得してください。」

ダークモードのテスト

「ダークモードに切り替えてスクリーンショットを撮影し、次にライトモードに切り替えてもう一度スクリーンショットを撮影してください。」

トラブルシューティング

idb が検出されない

ツールに [CGEvent fallback] と表示され、[cursor-free] と表示されない場合：

1. idb がインストールされていることを確認します：which idb を実行するか、~/Library/Python/3.x/bin/idb を確認します
2. MCP 設定の PATH 環境変数に idb のパスを追加します
3. または、PREFLIGHT_IDB_PATH を直接設定します

シミュレーターが見つからない

1. Simulator.app を開きます：open -a Simulator
2. デバイスを起動します：simulator_boot を使うか、xcrun simctl boot "iPhone 16 Pro" を実行します

アクセシビリティ権限エラー

1. 「システム設定」→「プライバシーとセキュリティ」→「アクセシビリティ」に移動します
2. ターミナルアプリ（Terminal.app、iTerm、Claude Code、Cursor、Windsurf など）を追加します

開発

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

ライセンス

MIT License — 詳細は LICENSE をご覧ください。