iOS Simulator MCP Server

iOS Simulator MCP サーバー

iOS シミュレーターを操作するための Model Context Protocol（MCP）サーバーです。このサーバーでは、iOS シミュレーターに関する情報の取得、UI 操作の実行、UI 要素の確認ができます。

セキュリティに関するお知らせ：1.3.3 未満のバージョンに存在したコマンドインジェクションの脆弱性は修正済みです。v1.3.3 以降に更新してください。詳細は SECURITY.md をご覧ください。

https://github.com/user-attachments/assets/a88e449c-8f1d-46a5-9816-0f97e071c460

🌟 紹介記事

このプロジェクトは、さまざまな出版物やリソースで紹介・言及されています。

• Claude Code のベストプラクティスに関する記事 - Anthropic のエンジニアリングブログでベストプラクティスとして紹介
• React Native Newsletter 第187号 - 人気の React Native コミュニティニュースレターで紹介
• Mobile Automation Newsletter - #56 - モバイルテストと自動化に関するリソースを長年紹介しているニュースレターで掲載
• punkeye/awesome-mcp-server のリスト - 人気の厳選 MCP サーバー集の一つに掲載

ツール

get_booted_sim_id

説明： 現在起動中の iOS シミュレーターの ID を取得します

パラメーター： なし

open_simulator

説明： iOS Simulator アプリケーションを開きます

パラメーター： なし

ui_describe_all

説明： iOS シミュレーターの画面全体について、アクセシビリティ情報を説明します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

ui_tap

説明： iOS シミュレーターの画面をタップします

パラメーター：

{
  /**
   * Press duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

ui_type

説明： iOS シミュレーターにテキストを入力します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /**
   * Text to input
   * Format: up to 500 characters; ASCII printable characters only (method "type")
   */
  text: string;
  /**
   * "type" (default) or "paste"
   */
  method?: "type" | "paste";
  /**
   * Method "paste" only: clear the focused field first (default false)
   */
  replace?: boolean;
}

method: "type"（デフォルト）は米国キーボードのようにキーを押すため、フランス語の AZERTY など別の配列では誤った文字が入力されます（[email protected] が ,obiletest2exq,ple:co, になります）。米国以外のキーボード配列や ASCII 以外のテキストには method: "paste" を使用してください。1 回の呼び出しに数秒かかり、約 230 ms ではなく、iOS がペーストを許可するよう求めない場合は約 2 秒（replace: true の場合は約 5 秒）、求める場合は最大約 11 秒かかります（iOS 26.5 および 27 で確認）。先にテキストフィールドをタップしてください。テキストはシミュレーターのペーストボードを介してフォーカス中のフィールドに貼り付けられ、iOS の「ペーストを許可」プロンプトは自動でタップされます。また、フィールドの内容を読み戻して確認します（セキュアフィールドの場合は長さのみ）。呼び出しが諦めた時点でプロンプトがまだ画面に表示されている場合を除き、以前のペーストボードのテキストは復元されます（画像などのテキスト以外の内容は復元されません）。その場合、テキストはペーストボードに残り、エラーによって、再試行するのではなく許可ボタンをタップするよう通知されます。replace: true を指定すると、フィールドを先にクリアします（例："type" で誤った文字が入力された後）。ペーストモードでは空のテキストと改行は拒否されます。fb-idb 1.5.1 以降と、最近の idb_companion が必要です（1.1.8 には --api axbridge がないため、ペーストはすべて「No focused text field found」で失敗します。brew upgrade idb-companion を実行し、その後 idb kill を実行してください）。

ui_swipe

説明： iOS シミュレーターの画面をスワイプします

パラメーター：

{
  /**
   * Swipe duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The starting x-coordinate */
  x_start: number;
  /** The starting y-coordinate */
  y_start: number;
  /** The ending x-coordinate */
  x_end: number;
  /** The ending y-coordinate */
  y_end: number;
  /** The size of each step in the swipe (default is 1) */
  delta?: number;
}

ui_describe_point

説明： iOS シミュレーターの画面上の指定した座標にあるアクセシビリティ要素を返します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

ui_find_element

説明： アクセシビリティツリーを検索し、指定された条件に一致する要素を返します

パラメーター：

{
  /** Array of search strings. An element matches if ANY string matches against its AXLabel or AXUniqueId */
  search: string[];
  /** Filter by element type (e.g. 'Button', 'StaticText', 'Group'). Case-insensitive exact match */
  type?: string;
  /** Match mode: 'substring' (default) or 'exact' */
  matchMode?: "substring" | "exact";
  /** Whether search matching is case-sensitive (default: false) */
  caseSensitive?: boolean;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

ui_view

説明： 現在のシミュレーター画面の圧縮スクリーンショットの画像コンテンツを取得します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

screenshot

説明： iOS シミュレーターのスクリーンショットを撮影します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** File path where the screenshot will be saved. If relative, it uses the directory specified by the `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` env var, or `~/Downloads` if not set. */
  output_path: string;
  /** Image format (png, tiff, bmp, gif, or jpeg). Default is png. */
  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
  /** Display to capture (internal or external). Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy (ignored, alpha, or black) */
  mask?: "ignored" | "alpha" | "black";
}

record_video

説明： simctl を直接使用して、iOS シミュレーターの動画を録画します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` or in `~/Downloads` if the environment variable is not set. */
  output_path?: string;
  /** Specifies the codec type: "h264" or "hevc". Default is "hevc". */
  codec?: "h264" | "hevc";
  /** Display to capture: "internal" or "external". Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black". */
  mask?: "ignored" | "alpha" | "black";
  /** Force the output file to be written to, even if the file already exists. */
  force?: boolean;
}

stop_recording

説明： killall を使用して、シミュレーターの動画録画を停止します

パラメーター： パラメーターなし

install_app

説明： iOS シミュレーターにアプリバンドル（.app または .ipa）をインストールします

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Path to the app bundle (.app directory or .ipa file) to install */
  app_path: string;
}

launch_app

説明： バンドル識別子を指定して、iOS シミュレーター上のアプリを起動します

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to launch (e.g., com.apple.mobilesafari) */
  bundle_id: string;
  /** Terminate the app if it is already running before launching */
  terminate_running?: boolean;
  /** Optional environment variables passed via SIMCTL_CHILD_ to simctl launch */
  env?: Record<string, string>;
}

注： simctl launch はすべてのバージョンの Xcode で --env/--envs をサポートしているわけではないため、環境変数は SIMCTL_CHILD_ を使用して渡します。

例：

{
  "bundle_id": "com.example.app",
  "terminate_running": true,
  "env": {
    "FOO": "bar",
    "BAZ": "qux"
  }
}

terminate_app

説明： バンドル識別子を指定して、iOS シミュレーター上で実行中のアプリを終了します。アプリを再インストールせずに、コールドスタート時の動作をテストしたり、クラッシュからの復旧を確認したりするのに便利です。

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to terminate (e.g., com.apple.mobilesafari) */
  bundle_id: string;
}

open_url

説明： iOS シミュレーターで URL またはディープリンクを開きます。https:// URL（Safari 経由）、カスタム URL スキーム、ユニバーサルリンクを処理します。ディープリンクのルーティングや OAuth リダイレクトフローのテストに不可欠です。

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The URL or deep link to open (e.g., https://example.com or myapp://screen/detail) */
  url: string;
}

list_apps

説明： iOS シミュレーターにインストールされているすべてのアプリについて、バンドル識別子と表示名をアルファベット順に一覧表示します。launch_app または terminate_app を呼び出す前に、バンドル ID を手動で調べる必要がなくなります。

パラメーター：

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

💡 ユースケース：MCP ツール呼び出しによる QA ステップ

この MCP サーバーを使うと、Model Context Protocol（MCP）クライアントと連携する AI アシスタントが、ツールを呼び出して品質保証タスクを実行できます。機能の実装直後に UI の一貫性と正しい動作を確認するのに役立ちます。

使用方法

機能を実装した後、MCP クライアント環境内で AI アシスタントに利用可能なツールを使うよう指示します。たとえば、Cursor のエージェントモードでは、以下のプロンプトを使って UI の操作をすばやく検証し、記録できます。

プロンプトの例

• UI 要素を確認する：

  Verify all accessibility elements on the current screen
  

• テキスト入力を確認する：

  Enter "QA Test" into the text input field and confirm the input is correct
  

• タップへの応答を確認する：

  Tap on coordinates x=250, y=400 and verify the expected element is triggered
  

• スワイプ操作を検証する：

  Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior
  

• 要素を詳細に確認する：

  Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality
  

• AI エージェントにシミュレーター画面を表示する：

  View the current simulator screen
  

• スクリーンショットを撮影する：

  Take a screenshot of the current simulator screen and save it to my_screenshot.png
  

• 動画を録画する：

  Start recording a video of the simulator screen (saves to the default output directory, which is `~/Downloads` unless overridden by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR`)
  

• 録画を停止する：

  Stop the current simulator screen recording
  

• アプリをインストールする：

  Install the app at path/to/MyApp.app on the simulator
  

• アプリを起動する：

  Launch the Safari app (com.apple.mobilesafari) on the simulator
  

🧭 ヒント：ディープリンクで画面に直接移動する

エージェントは、深くネストされた画面にたどり着くまでタップやスワイプを繰り返し、多くの試行を費やすことがあります。アプリが URL スキーム（またはユニバーサルリンク）を登録している場合、手順を追って移動するより、対象の画面に直接移動するほうが通常は速くなります。

uri-scheme を使ってディープリンクを開けます。

npx uri-scheme open "myapp://products/42" --ios

このコマンドは、現在起動しているシミュレーターを対象とします。内部的には、次のコマンドと同等です。

xcrun simctl openurl booted "myapp://products/42"

どちらもカスタムスキーム（myapp://...）と Web URL（https://...）で動作します。アプリが設定されている場合、Web URL はユニバーサルリンクを起動します。

プロンプトの例：

Open the deep link myapp://products/42 in the simulator, then verify the product
details screen is shown

エージェントの反復回数を減らすには、これを使ってテスト対象の画面にディープリンクで移動し、その後 UI ツール（ui_describe_all、ui_tap、ui_view、…）で検証します。

前提条件

• Node.js 20 以降
• macOS（iOS シミュレーターは macOS でのみ利用可能です）
• Xcode と iOS シミュレーターがインストールされていること
• Facebook の IDB ツール：idb_companion バイナリと fb-idb Python クライアント。インストール手順については TROUBLESHOOTING.md、method: "paste" で必要なバージョンについては ui_type を参照してください

インストール

このセクションでは、iOS Simulator MCP サーバーをさまざまな Model Context Protocol（MCP）クライアントと連携する手順を説明します。

Cursor へのインストール

Cursor は ~/.cursor/mcp.json にある設定ファイルを通じて MCP サーバーを管理します。

方法 1：NPX を使用（推奨）

1. Cursor の MCP 設定ファイルを編集します。Cursor から直接開くか、次のようなコマンドを使用できます。

   # デフォルトのエディターで開く（または 'code'、'vim' などを使用）
   open ~/.cursor/mcp.json
   # 利用可能な場合は Cursor のコマンドを使用
   # cursor ~/.cursor/mcp.json
   

2. mcpServers セクションに iOS シミュレーターサーバーの設定を追加するか、既存の設定を更新します。

   {
     "mcpServers": {
       // ... 他のサーバーがここに記載されている場合があります ...
       "ios-simulator": {
         "command": "npx",
         "args": ["-y", "ios-simulator-mcp"]
       }
     }
   }
   

   特に mcpServers がすでに存在する場合は、JSON の構造が有効であることを確認してください。

   pnpm を使用する場合は、代わりに dlx ランナーを使用してください。

   {
     "mcpServers": {
       "ios-simulator": {
         "command": "pnpm",
         "args": ["dlx", "ios-simulator-mcp"]
       }
     }
   }
   

3. 変更を反映するため、Cursor を再起動します。

方法 2：ローカル開発

1. このリポジトリをクローンします。

   git clone https://github.com/joshuayoes/ios-simulator-mcp
   cd ios-simulator-mcp
   

2. 依存関係をインストールします（デフォルトは npm ですが、pnpm もサポートされています）。

   npm install
   # または、pnpm を使用（コミット済みの pnpm-lock.yaml からインストール）：
   pnpm install
   

3. プロジェクトをビルドします。

   npm run build
   # または：
   pnpm run build
   

4. Cursor の MCP 設定ファイルを編集します（方法 1 を参照）。
5. mcpServers セクションに、ローカルビルドを指定して追加するか、既存の設定を更新します。

   {
     "mcpServers": {
       // ... 他のサーバーがここに記載されている場合があります ...
       "ios-simulator": {
         "command": "node",
         "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
       }
     }
   }
   

   重要： /full/path/to/your/ を、ios-simulator-mcp リポジトリをクローンした場所の絶対パスに置き換えてください。
6. 変更を反映するため、Cursor を再起動します。

Claude Code へのインストール

Claude Code CLI は、claude mcp コマンドを使用するか、設定ファイルを直接編集して MCP サーバーを管理できます。Claude Code の MCP 設定の詳細については、公式ドキュメントを参照してください。

方法 1：NPX を使用（推奨）

1. claude mcp add コマンドを使用してサーバーを追加します。

   claude mcp add ios-simulator npx ios-simulator-mcp
   # または、pnpm を使用：
   claude mcp add ios-simulator -- pnpm dlx ios-simulator-mcp
   

2. 必要に応じて、実行中の Claude Code セッションを再起動します。

方法 2：ローカル開発

1. Cursor の「ローカル開発」の手順 1～3 に従って、このリポジトリをクローンし、依存関係をインストールして、プロジェクトをビルドします。
2. claude mcp add コマンドを使用して、ローカルビルドを指定してサーバーを追加します。

   claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"
   

   重要： /full/path/to/your/ を、ios-simulator-mcp リポジトリをクローンした場所の絶対パスに置き換えてください。
3. 必要に応じて、実行中の Claude Code セッションを再起動します。

設定

環境変数

変数	説明	例
IOS_SIMULATOR_MCP_FILTERED_TOOLS	登録対象から除外するツール名をカンマ区切りで指定します。	screenshot,record_video,stop_recording
IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR	スクリーンショットやビデオ録画などの出力ファイルのデフォルトディレクトリを指定します。設定しない場合は、~/Downloads が使用されます。エージェントのファイルシステムへのアクセスが限られている場合に便利です。	~/Code/awesome-project/tmp
IOS_SIMULATOR_MCP_IDB_PATH	IDB 実行ファイルのカスタムパスを指定します。設定しない場合は、PATH に含まれていることを前提として idb が使用されます。IDB が標準以外の場所にインストールされている場合に便利です。	~/bin/idb or /usr/local/bin/idb

設定例

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"],
      "env": {
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp",
        "IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb"
      }
    }
  }
}

MCP レジストリのサーバー一覧

ライセンス

MIT