iOS Simulator MCP Server

iOS 模拟器 MCP 服务

用于与 iOS 模拟器交互的模型上下文协议（MCP）服务。此服务允许你获取 iOS 模拟器的信息、控制 UI 交互并检查 UI 元素，从而与 iOS 模拟器交互。

安全提示：已修复版本 < 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 Simulator 中整个屏幕的无障碍信息

参数：

{
  /**
   * 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 Simulator 中的屏幕

参数：

{
  /**
   * 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 Simulator 中输入文本

参数：

{
  /**
   * 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"；每次调用需要几秒，而不是约 230 ms：如果 iOS 未询问是否允许粘贴，则约需 2 s（设置 replace: true 时约需 5 s）；如果 iOS 询问，则最多需约 11 s（在 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 Simulator 中滑动屏幕

参数：

{
  /**
   * 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 Simulator 屏幕上给定坐标处的无障碍元素

参数：

{
  /**
   * 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 Simulator 的屏幕截图

参数：

{
  /**
   * 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 Simulator 视频

参数：

{
  /**
   * 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 Simulator 上安装应用包（.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

**描述：**根据 bundle 标识符在 iOS Simulator 上启动应用

参数：

{
  /**
   * 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_CHILD_ 传递，因为并非所有 Xcode 版本都支持 simctl launch 的 --env/--envs。

示例：

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

terminate_app

**描述：**根据 bundle 标识符终止 iOS Simulator 上正在运行的应用。适用于测试冷启动流程，以及在不重新安装应用的情况下验证崩溃恢复。

参数：

{
  /**
   * 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 Simulator 中打开 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 Simulator 上所有已安装的应用及其 bundle 标识符和显示名称，并按字母顺序排序。无需在调用 launch_app 或 terminate_app 前手动查找 bundle 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 一致性和行为正确。

使用方法

实现功能后，在 AI 助手的 MCP 客户端环境中指示其使用可用工具。例如，在 Cursor 的 Agent 模式下，可以使用以下提示词快速验证并记录 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 Agent 显示模拟器屏幕：

  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
  

🧭 提示：通过深层链接直达屏幕

Agent 可能会耗费很多轮操作，通过点击和滑动前往深层嵌套的路由。当应用注册了 URL 方案（或通用链接）时，通常直接跳转到目标屏幕会比逐步导航更快。

你可以使用 uri-scheme 打开深层链接：

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

这会针对当前已启动的模拟器。底层等效于：

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

两种方式都适用于自定义方案（myapp://...）和 Web URL（https://...，如果应用已配置通用链接，则会触发通用链接）。

示例提示词：

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

使用此方法缩短 Agent 的操作循环：通过深层链接跳转到待测屏幕，然后使用 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"]
       }
     }
   }
   

   确保 JSON 结构有效，尤其是在 mcpServers 已存在时。

   如果更喜欢使用 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。如果你的 Agent 对文件系统的访问权限有限，这会很有用。	~/Code/awesome-project/tmp
IOS_SIMULATOR_MCP_IDB_PATH	指定 IDB 可执行文件的自定义路径。如果未设置，将使用 idb（假设它位于你的 PATH 中）。如果 IDB 安装在非标准位置，此设置会很有用。	~/bin/idb 或 /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