AI导哈

iOS模拟器交互工具

一个通过MCP协议提供iOS模拟器交互功能的工具，包括截图、UI检查、点击、滑动、设置GPS位置等操作。

  • by whitesmith
  • Python
  • 本地部署
  • 17 星标
  • 更新于
在 GitHub 查看 whitesmith/ios-simulator-mcp

使用说明

iOS模拟器MCP

一 MCP（模型上下文协议） 提供与iOS模拟器交互工具的服务器。截图、检查UI层次结构、点击、滑动、键入、设置GPS位置等。

可与任何兼容MCP的客户端配合使用，包括 克劳德代码, 克劳德桌面，以及 其他.

快速开始

# 1. Install prerequisites
xcode-select --install
brew tap facebook/fb
brew install idb-companion uv pipx
pipx ensurepath
pipx install fb-idb --python python3.11

# 2. Clone and install the MCP
git clone https://github.com/whitesmith/ios-simulator-mcp.git ~/ios-simulator-mcp
cd ~/ios-simulator-mcp
uv sync

# 3. Add to Claude Code settings (see Configuration section below)
claude mcp add ios-simulator \
  -- uv run --directory ~/ios-simulator-mcp ios-simulator-mcp

# 4. Restart Claude Code

建筑

此MCP使用两个底层工具：

工具 来源 用于
xcrun simctl 内置Xcode 模拟器管理、截图、位置、URL
idb Facebook IDB UI交互（点击、滑动、键入）、UI层次结构、应用程序管理

先决条件

Xcode命令行工具

xcode-select --install

2.脸书IDB（iOS开发桥）

IDB是UI交互（点击、滑动、键入、UI层次结构）所必需的。它有 两个组件 两者都必须安装：

a） idb伴侣（后端服务）

brew tap facebook/fb
brew install idb-companion

b） idb CLI（命令行界面）

这 idb 命令来自 fb-idb Python包。使用pipx全局安装：

# Install pipx if you don't have it
brew install pipx
pipx ensurepath

# Install fb-idb globally (use Python 3.11 for compatibility)
pipx install fb-idb --python python3.11

备注：The fb-idb 该包与Python 3.14存在兼容性问题。使用Python 3.11或3.12。

验证IDB安装

# Check idb-companion
which idb_companion
# Should output: /opt/homebrew/bin/idb_companion

# Check idb CLI
which idb
# Should output: ~/.local/bin/idb

# Test connectivity
idb list-targets
# Should list all available simulators

3.uv（Python包管理器）

brew install uv

安装

克隆存储库并安装依赖项：

git clone https://github.com/whitesmith/ios-simulator-mcp.git ~/ios-simulator-mcp
cd ~/ios-simulator-mcp
uv sync

配置

克劳德代码

最快的方法是使用CLI：

claude mcp add ios-simulator -- uv run --directory /Users/yourname/ios-simulator-mcp ios-simulator-mcp

或手动添加到 ~/.claude/settings.json （全球）或 .mcp.json 在项目根目录中（特定于项目）：

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/yourname/ios-simulator-mcp", "ios-simulator-mcp"]
    }
  }
}

替换 /Users/yourname/ios-simulator-mcp 使用克隆存储库的绝对路径。

备注：使用绝对路径（例如。， /Users/yourname/ios-simulator-mcp)，不 ~，因为JSON值不由shell处理。

然后重新启动Claude Code或运行 /mcp 重新加载MCP服务器。

克劳德桌面

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ios-simulator": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/yourname/ios-simulator-mcp", "ios-simulator-mcp"]
    }
  }
}

然后重新启动Claude Desktop。

可用工具

模拟器管理

工具 说明
list_simulators 列出所有可用的模拟器，包括状态和UDID
boot_simulator 启动模拟器（如果未指定，则自动选择）
get_device_info 获取有关已连接模拟器的信息

截图和UI检查

工具 说明
screenshot 截图（返回图像进行目视检查）
get_ui_hierarchy 获取包含位置和标签的UI元素树

用户交互

工具 说明
tap 点击x、y坐标
long_press 长按坐标
swipe 从一个点滑动到另一个点
type_text 在焦点字段中键入文本
tap_and_type 点击字段，然后键入
press_button 按下硬件按钮（主页、锁、siri、音量）
shake 触发抖动手势

应用程序管理

工具 说明
launch_app 按捆绑包ID启动应用程序
terminate_app 关闭正在运行的应用程序
install_app 安装.app捆绑包
uninstall_app 按捆绑包ID卸载应用程序
open_url 开放URL（非常适合深度链接）

位置

工具 说明
set_location 设置GPS坐标
clear_location 清晰的模拟位置

效用

工具 说明
wait 等待指定秒数

使用示例

配置后，您的MCP客户端可以自动使用这些工具。以下是一些使用Claude Code的示例：

实现功能后的视觉验证

Claude: Let me check how the new balance screen looks.
[Uses screenshot tool]
Claude: I can see the balance card is displaying correctly with the $50.00
amount. However, the "Add Funds" button appears to be cut off on the right edge.
Let me fix the padding...

测试流量

Claude: I'll test the login flow.
[Uses launch_app with bundle_id "com.example.myapp"]
[Uses screenshot to see current state]
[Uses get_ui_hierarchy to find the email field coordinates]
[Uses tap_and_type to enter email]
[Uses tap to press login button]
[Uses wait for 2 seconds]
[Uses screenshot to verify login succeeded]

测试基于位置的功能

Claude: Let me test the pickup location feature in San Francisco.
[Uses set_location with lat=37.7749, lng=-122.4194]
[Uses screenshot to verify map updated]

故障排除

MCP工具未出现在Claude代码中

  1. 检查MCP是否已配置 ~/.claude/settings.json 或 .mcp.json
  2. 重新启动Claude Code或运行 /mcp 重新加载服务器
  3. 检查MCP服务器启动中的错误

“idb：找不到命令”

这是最常见的问题。这 fb-idb Python包必须全局安装，而不仅仅是在MCP的虚拟环境中：

# Install pipx if needed
brew install pipx
pipx ensurepath

# Install fb-idb globally with Python 3.11 (3.14 has compatibility issues)
pipx install fb-idb --python python3.11

# Verify
which idb  # Should show ~/.local/bin/idb

“未连接模拟器”

MCP将自动连接到已启动的模拟器。如果没有启动，请使用：

boot_simulator with device_name="iPhone 15 Pro"

或者手动启动一个：

xcrun simctl boot "iPhone 16"

IDB连接问题

重新启动idb伴侣：

idb kill
idb_companion --udid <simulator-udid>

或手动连接：

idb connect <simulator-udid>

UI层次结构返回空

确保模拟器有一个打开的应用程序。主屏幕或系统对话框上的可访问性树可能为空。

截图失败

确保模拟器完全启动且可见。测试：

xcrun simctl io booted screenshot /tmp/test.png

fb-idb的Python版本问题

如果您看到以下错误 RuntimeError: There is no current event loop，您可能使用的Python 3.14具有与fb-idb不兼容的asyncio更改。使用较旧的Python重新安装：

pipx uninstall fb-idb
pipx install fb-idb --python python3.11

发展

cd ~/ios-simulator-mcp
uv sync
uv run ios-simulator-mcp  # runs the server directly (for testing)

运作原理

当MCP客户端调用工具时：

  1. 模拟器管理 (list_simulators, boot_simulator)用途 xcrun simctl
  2. 截图 使用 xcrun simctl io <udid> screenshot
  3. UI交互 (tap, swipe, type_text)使用 idb ui 命令
  4. UI层级 用途 idb ui describe-all 获取可访问性树
  5. 应用管理 (launch_app, terminate_app)用途 idb 命令
  6. 位置 用途 xcrun simctl location

MCP会自动连接到已启动的模拟器，或者在没有运行模拟器的情况下启动最新的iPhone。

局限性

  • 仅限macOS -iOS模拟器仅在macOS上运行
  • 仅模拟器 -不支持物理iOS设备（idb支持，但此MCP是为模拟器配置的）
  • 应用程序屏幕上的UI层次结构 -辅助功能树可能为空，或者在主屏幕、系统对话框或没有辅助功能标签的应用程序上受到限制
  • 基于坐标的交互 -轻击和滑动使用绝对坐标；你需要使用 get_ui_hierarchy 查找元素位置
  • 无手势记录 -不支持复杂的多点触控手势
  • 屏幕截图大小 -屏幕截图被压缩为JPEG格式，上限约为2MB，以实现高效传输

许可证

麻省理工学院

相关 MCP