iOS 模拟器 MCP 服务器

这是一个用于与 iOS 模拟器交互的模型上下文协议 (MCP) 服务器。该服务器允许您获取模拟器信息、控制 UI 交互以及检查 UI 元素，从而实现对 iOS 模拟器的全面操作。

安全提示：低于 1.3.3 版本中存在命令注入漏洞，现已修复。请升级至 1.3.3 或更高版本。详情请参阅 SECURITY.md。

https://github.com/user-attachments/assets/453ebe7b-cc93-4ac2-b08d-0f8ac8339ad3

🌟 被推荐

该项目已被多家媒体和资源收录并提及：

• Claude Code 最佳实践文章 - Anthropic 工程博客中的最佳实践分享
• React Native Newsletter 第 187 期 - 在最受欢迎的 React Native 社区简报中被重点介绍
• 移动自动化简报 - 第 56 期 - 长期关注移动测试与自动化资源的简报中有所提及
• punkeye/awesome-mcp-server 列表 - 被收录于最受欢迎的精选 MCP 服务器合集之一

工具

get_booted_sim_id

描述：获取当前已启动的 iOS 模拟器的 ID

参数：无参数

open_simulator

描述：打开 iOS 模拟器应用程序

参数：无参数

ui_describe_all

描述：描述 iOS 模拟器中整个屏幕的可访问性信息

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
}

ui_tap

描述：在 iOS 模拟器屏幕上执行点击操作

参数：

{
  /**
   * 按压持续时间，单位为秒（允许使用小数）
   */
  duration?: string;
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** X 坐标 */
  x: number;
  /** Y 坐标 */
  y: number;
}

ui_type

描述：向 iOS 模拟器输入文本

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /**
   * 要输入的文本
   * 格式：仅限 ASCII 可打印字符
   */
  text: string;
}

ui_swipe

描述：在 iOS 模拟器屏幕上执行滑动操作

参数：

{
  /**
   * 滑动持续时间，单位为秒（允许使用小数）
   */
  duration?: string;
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** 起始 X 坐标 */
  x_start: number;
  /** 起始 Y 坐标 */
  y_start: number;
  /** 结束 X 坐标 */
  x_end: number;
  /** 结束 Y 坐标 */
  y_end: number;
  /** 滑动过程中每一步的增量（默认为 1） */
  delta?: number;
}

ui_describe_point

描述：返回 iOS 模拟器屏幕上指定坐标处的可访问性元素

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** X 坐标 */
  x: number;
  /** Y 坐标 */
  y: number;
}

ui_view

描述：获取当前模拟器视图的压缩截图图像内容

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
}

screenshot

描述：截取 iOS 模拟器的屏幕快照

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** 截图保存的文件路径。如果是相对路径，则使用 IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR 环境变量指定的目录；若未设置，则保存到 ~/Downloads。 */
  output_path: string;
  /** 图像格式（png、tiff、bmp、gif 或 jpeg）。默认为 png。 */
  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
  /** 要捕获的显示画面（内部或外部）。默认值取决于设备类型。 */
  display?: "internal" | "external";
  /** 对于非矩形屏幕，按策略处理遮罩（忽略、透明或黑色）。 */
  mask?: "ignored" | "alpha" | "black";
}

record_video

描述：使用 simctl 直接录制 iOS 模拟器视频

参数：

{
  /** 可选的输出路径。若未提供，则会使用默认名称。文件将保存在 IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR 指定的目录中，或在环境变量未设置时保存到 ~/Downloads。 */
  output_path?: string;
  /** 指定编解码器类型：“h264”或“hevc”。默认为 “hevc”。 */
  codec?: "h264" | "hevc";
  /** 要捕获的显示画面：“internal” 或 “external”。默认值取决于设备类型。 */
  display?: "internal" | "external";
  /** 对于非矩形屏幕，按策略处理遮罩：“ignored”、“alpha” 或 “black”。 */
  mask?: "ignored" | "alpha" | "black";
  /** 强制写入输出文件，即使文件已存在。 */
  force?: boolean;
}

stop_recording

描述：使用 killall 命令停止模拟器视频录制

参数：无参数

install_app

描述：在 iOS 模拟器上安装应用包（.app 或 .ipa 文件）

参数：

{
  /**
   * 目标设备的 UDID，也可通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** 要安装的应用包路径（.app 目录或 .ipa 文件） */
  app_path: string;
}

launch_app

描述: 通过捆绑标识符在 iOS 模拟器上启动应用

参数:

{
  /**
   * 目标设备的 UDID，也可以通过 IDB_UDID 环境变量设置
   * 格式：UUID（8-4-4-4-12 个十六进制字符）
   */
  udid?: string;
  /** 要启动的应用程序的捆绑标识符（例如 com.apple.mobilesafari） */
  bundle_id: string;
  /** 如果应用程序已经在运行，则在启动前将其终止 */
  terminate_running?: boolean;
}

💡 使用场景：通过 MCP 工具调用进行 QA 测试

该 MCP 服务器允许集成 Model Context Protocol (MCP) 客户端的 AI 助手通过工具调用来执行质量保证任务。这在功能实现后非常有用，可以帮助确保 UI 的一致性和正确的行为。

使用方法

在功能实现之后，指示您的 AI 助手在其 MCP 客户端环境中使用可用的工具。例如，在 Cursor 的代理模式下，您可以使用以下提示快速验证并记录 UI 交互。

示例提示

• 验证 UI 元素：

  验证当前屏幕上的所有可访问性元素
  

• 确认文本输入：

  在文本输入框中输入“QA Test”，并确认输入内容正确
  

• 检查点击响应：

  点击坐标 x=250, y=400，并验证预期的元素是否被触发
  

• 验证滑动操作：

  从 x=150, y=600 滑动到 x=150, y=100，并确认行为正确
  

• 详细检查元素：

  描述位置 x=300, y=350 处的 UI 元素，以确保其标签和功能正常
  

• 向 AI 代理展示模拟器屏幕：

  查看当前模拟器屏幕
  

• 截取屏幕截图：

  截取当前模拟器屏幕的截图，并保存为 my_screenshot.png
  

• 录制视频：

  开始录制模拟器屏幕的视频（保存到默认输出目录，默认为 ~/Downloads，除非被 IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR 覆盖）
  

• 停止录制：

  停止当前模拟器屏幕的录制
  

• 安装应用：

  将位于 path/to/MyApp.app 的应用安装到模拟器上
  

• 启动应用：

  在模拟器上启动 Safari 应用程序（com.apple.mobilesafari）
  

先决条件

• Node.js
• macOS（因为 iOS 模拟器仅在 macOS 上可用）
• 已安装 Xcode 和 iOS 模拟器
• Facebook IDB 工具 (参见安装指南)

安装

本节提供了将 iOS 模拟器 MCP 服务器与不同 Model Context Protocol (MCP) 客户端集成的说明。

使用 Cursor 安装

Cursor 通过位于 ~/.cursor/mcp.json 的配置文件管理 MCP 服务器。

方法一：使用 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 已经存在的情况下。
3. 重启 Cursor 以使更改生效。

方法二：本地开发

1. 克隆此仓库：

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

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

4. 编辑您的 Cursor MCP 配置文件（如方法一所示）。
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 配置的更多详细信息，请参阅官方文档。

方法一：使用 NPX（推荐）

1. 使用 claude mcp add 命令添加服务器：

   claude mcp add ios-simulator npx ios-simulator-mcp
   

2. 如有必要，重启任何正在运行的 Claude Code 会话。

方法二：本地开发

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 可执行文件的自定义路径。如果未设置，将使用 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

ios-simulator-mcp 快速上手指南

ios-simulator-mcp 是一个基于模型上下文协议（MCP）的服务器工具，允许 AI 助手直接与 macOS 上的 iOS 模拟器进行交互。你可以用它来检查 UI 元素、执行点击/滑动/输入操作、截屏录屏以及安装启动应用，非常适合自动化测试和 QA 流程。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS（iOS 模拟器仅支持 macOS）。
• 运行时环境：已安装 Node.js。
• 开发工具：已安装 Xcode 并配置好 iOS Simulators。
• 核心依赖：必须安装 Facebook 的 IDB 工具。
  • 推荐使用 Homebrew 安装：

    brew tap facebook/fb
    brew install idb-companion
    

安装步骤

你可以根据使用的 MCP 客户端选择以下一种安装方式。

方式一：Cursor 编辑器（推荐）

Cursor 通过 ~/.cursor/mcp.json 配置文件管理 MCP 服务。

1. 打开配置文件：

   open ~/.cursor/mcp.json
   

2. 在 mcpServers 对象中添加以下配置（使用 npx 无需本地构建）：

   {
     "mcpServers": {
       "ios-simulator": {
         "command": "npx",
         "args": ["-y", "ios-simulator-mcp"]
       }
     }
   }
   

3. 重启 Cursor 使配置生效。

方式二：Claude Code CLI

如果你使用 Claude Code 命令行工具：

1. 运行以下命令添加服务：

   claude mcp add ios-simulator npx ios-simulator-mcp
   

2. 重启当前的 Claude Code 会话。

方式三：本地开发模式

如果你需要修改源码或调试：

1. 克隆仓库并安装依赖：

   git clone https://github.com/joshuayoes/ios-simulator-mcp
   cd ios-simulator-mcp
   npm install
   npm run build
   

2. 在 MCP 配置文件中指向本地构建文件（以 Cursor 为例）：

   {
     "mcpServers": {
       "ios-simulator": {
         "command": "node",
         "args": ["/绝对路径/to/ios-simulator-mcp/build/index.js"]
       }
     }
   }
   

   注意：请将 /绝对路径/to/ 替换为你本地的实际路径。

基本使用

安装完成后，在支持 MCP 的 AI 助手（如 Cursor Agent 或 Claude Code）中，直接通过自然语言指令调用工具即可。AI 会自动识别并调用相应的 MCP 工具。

1. 查看模拟器屏幕

让 AI 获取当前模拟器的界面截图或描述：

"View the current simulator screen" "Verify all accessibility elements on the current screen"

2. 执行 UI 交互

让 AI 执行点击、输入或滑动手势：

"Tap on coordinates x=250, y=400" "Enter 'QA Test' into the text input field" "Swipe from x=150, y=600 to x=150, y=100"

3. 应用管理

安装或启动特定的 App：

"Install the app at path/to/MyApp.app on the simulator" "Launch the Safari app (com.apple.mobilesafari) on the simulator"

4. 记录与截图

保存测试证据：

"Take a screenshot of the current simulator screen and save it to my_screenshot.png" "Start recording a video of the simulator screen" "Stop the current simulator screen recording"

---

安全提示：请确保使用 v1.3.3 或更高版本，以修复早期版本中存在的命令注入漏洞。