Skip to main content
Glama

iOS 模拟器 MCP 服务器

安装 MCP 服务器 NPM 版本

一个用于与 iOS 模拟器交互的模型上下文协议 (MCP) 服务器。该服务器允许您通过获取模拟器信息、控制 UI 交互和检查 UI 元素来与 iOS 模拟器进行交互。

安全公告:已修复 < 1.3.3 版本中存在的命令注入漏洞。请更新至 v1.3.3 或更高版本。详情请参阅 SECURITY.md

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

🌟 特色推荐

本项目已被多家出版物和资源收录并提及:

Related MCP server: iOS Device Control MCP Server

工具

get_booted_sim_id

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

参数: 无参数

open_simulator

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

参数: 无参数

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: ASCII printable characters only
   */
  text: string;
}

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

描述: 通过 bundle identifier 在 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_CHILD_ 传递,因为并非所有 Xcode 版本都支持 simctl launch--env/--envs 参数。

示例:

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

💡 用例:通过 MCP 工具调用进行 QA 步骤

此 MCP 服务器允许与模型上下文协议 (MCP) 客户端集成的 AI 助手通过进行工具调用来执行质量保证 (QA) 任务。这在实现功能后立即使用,有助于确保 UI 的一致性和正确的行为。

如何使用

在功能实现后,指示您的 AI 助手在其 MCP 客户端环境中使用可用工具。例如,在 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

先决条件

安装

本节提供了将 iOS 模拟器 MCP 服务器与不同模型上下文协议 (MCP) 客户端集成的说明。

使用 Cursor 安装

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

选项 1:使用 NPX (推荐)

  1. 编辑您的 Cursor MCP 配置文件。您通常可以直接从 Cursor 打开它,或者使用如下命令:

    # Open with your default editor (or use 'code', 'vim', etc.)
    open ~/.cursor/mcp.json
    # Or use Cursor's command if available
    # cursor ~/.cursor/mcp.json
  2. 添加或更新 mcpServers 部分,包含 iOS 模拟器服务器配置:

    {
      "mcpServers": {
        // ... other servers might be listed here ...
        "ios-simulator": {
          "command": "npx",
          "args": ["-y", "ios-simulator-mcp"]
        }
      }
    }

    确保 JSON 结构有效,特别是如果 mcpServers 已经存在。

  3. 重启 Cursor 以使更改生效。

选项 2:本地开发

  1. 克隆此仓库:

    git clone https://github.com/joshuayoes/ios-simulator-mcp
    cd ios-simulator-mcp
  2. 安装依赖:

    npm install
  3. 构建项目:

    npm run build
  4. 编辑您的 Cursor MCP 配置文件(如选项 1 所示)。

  5. 添加或更新 mcpServers 部分,指向您的本地构建:

    {
      "mcpServers": {
        // ... other servers might be listed here ...
        "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
  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 可执行文件的自定义路径。如果未设置,将使用 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

Install Server
A
license - permissive license
A
quality
A
maintenance

Maintenance

Maintainers
9dResponse time
6wRelease cycle
9Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…

  • Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.

  • MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joshuayoes/ios-simulator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server