使用说明

ios sim mcp

用于iOS模拟器自动化的模型上下文协议（MCP）服务器。使AI助手能够与模拟器中运行的iOS应用程序进行视觉交互。

运作原理

此MCP服务器包装 Facebook的idb（iOS开发桥梁）提供对iOS模拟器的隔离、无头控制。与控制鼠标/键盘的方法不同，idb将触摸事件直接注入模拟器：

在后台运行 -不会接管你的屏幕
孤立的 -你可以在电脑运行时使用它
可靠的 -使用与Facebook测试相同的基础设施

需求

macOS （iOS模拟器仅在Mac上运行）
Xcode 已安装iOS模拟器
Node.js 18+
互联网数据库 （按照以下步骤安装）

正在安装idb

# Install idb-companion (the daemon)
brew tap facebook/fb
brew install idb-companion

# Install idb (the Python CLI client)
pip3 install fb-idb

安装

选项1：从npm安装（推荐）

npm install -g ios-sim-mcp

选项2：克隆和构建

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

使用Claude代码

claude mcp add ios-sim -s user -- npx ios-sim-mcp

或者，如果从源代码安装：

claude mcp add ios-sim -s user -- node /path/to/ios-sim-mcp/dist/index.js

坐标系

所有坐标均以点为单位，而非像素。

积分是iOS使用的独立于设备的单位
使用 get_screen_size 获取像素和点维度
使用 describe_screen 以点为单位获取元素坐标
常见尺寸：iPhone 17 Pro为393x852点

常见工作流

1.入门

list_simulators              → Find available simulators and their UDIDs
boot_simulator(udid)         → Boot the simulator you want
screenshot                   → Verify it's running, see the screen

2.查找和点击UI元素

# Option A: Search by label (recommended)
find_elements(label: "Sign In")  → Returns elements with matching labels
tap_element(label: "Sign In")    → Find and tap in one step

# Option B: Use coordinates from accessibility tree
describe_screen              → Get all elements with their frame coordinates
tap(x: 196, y: 425)          → Tap at the element's center

3.填写表格

tap_element(label: "Email")      → Focus the email field
type_text(text: "user@test.com") → Type the email
press_key(key: "tab")            → Move to next field
type_text(text: "password123")   → Type the password
tap_element(label: "Submit")     → Submit the form

4.滚动和导航

# Scroll down (swipe up)
swipe(startX: 200, startY: 600, endX: 200, endY: 200)

# Scroll up (swipe down)
swipe(startX: 200, startY: 200, endX: 200, endY: 600)

# Go back to home screen
press_button(button: "home")

5.测试深度链接

open_url(url: "myapp://profile/settings")  → Open custom URL scheme
screenshot                                  → Verify the right screen loaded

可用工具

模拟器管理

工具	描述	返回
`list_simulators`	列出所有状态为	Array的iOS模拟器： `[{name, udid, state, type, os_version}]`
`boot_simulator`	通过UDID启动模拟器	确认字符串
`shutdown_simulator`	关机模拟器	确认字符串

视觉反馈

工具	描述	返回
`screenshot`	捕获模拟器屏幕	Base64 PNG图像
`get_screen_size`	获取尺寸	`{pixels: {w,h}, points: {w,h}, scale}`

UI发现

工具	描述	返回
`describe_screen`	获取所有UI元素	数组： `[{type, label, value, frame, enabled}]`
`describe_point`	获取坐标处的元素	元素信息字符串
`find_elements`	按标签搜索元素	匹配元素数组

交互

工具	描述	返回
`tap`	点击x、y坐标（点）	确认字符串
`tap_element`	按标签查找元素并点击它	用坐标确认
`swipe`	在两点之间滑动	确认字符串
`type_text`	在焦点字段中键入	确认字符串
`press_key`	按键盘键（enter、delete、tab、escape）	确认字符串
`press_button`	按下设备按钮（主页、锁、siri、apple_pay）	确认字符串

应用程序管理

工具	描述	返回
`list_apps`	列出已安装的应用程序	带捆绑包ID的应用程序列表
`launch_app`	按捆绑包ID启动应用程序	确认字符串
`terminate_app`	终止正在运行的应用程序	确认字符串
`open_url`	打开URL（http或自定义方案）	确认字符串

元素发现

这 describe_screen 工具以以下格式返回UI元素：

[
  {
    "type": "Button",
    "label": "Sign In",
    "value": null,
    "frame": {"x": 147, "y": 400, "width": 100, "height": 50},
    "enabled": true
  },
  {
    "type": "TextField",
    "label": "Email",
    "value": "",
    "frame": {"x": 20, "y": 200, "width": 353, "height": 44},
    "enabled": true
  }
]

要点击元素，请计算其中心：

centerX = frame.x + frame.width / 2
centerY = frame.y + frame.height / 2

或使用 tap_element 这是自动完成的。

建筑学

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude/LLM    │────▶│  ios-sim-mcp    │────▶│  idb companion  │
│                 │ MCP │  (this server)  │ CLI │  (Facebook's)   │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                                                         ▼
                                                ┌─────────────────┐
                                                │  iOS Simulator  │
                                                │  (Xcode)        │
                                                └─────────────────┘

配置

服务器正在查找 idb 在这些地点：

IDB_PATH 环境变量（如果设置）
~/Library/Python/3.9/bin/idb
/opt/homebrew/bin/idb
/usr/local/bin/idb
系统路径

故障排除

“未找到已启动的模拟器”

使用 list_simulators 找到可用的模拟器，然后 boot_simulator 与UDID。

“找不到idb”

安装idb： pip3 install fb-idb

“未连接同伴”

idb伴侣通常会自动启动。如果问题仍然存在：

idb_companion --udid <simulator-udid>

点击未击中正确的元素

坐标必须在点，不是像素
使用 describe_screen 获取精确的元素框架
使用 tap_element 带有元件标签，可实现更可靠的攻丝

按标签找不到元素

使用 describe_screen 查看所有可用标签
标签是不区分大小写的部分匹配
某些元素可能未设置可访问性标签

许可证

麻省理工学院

鸣谢

Facebook ID -底层自动化框架
模型上下文协议 -协议规范