内容
# ios-sim-mcp
iOS 模拟器 MCP 服务器，用于 iOS 模拟器自动化。使 AI 助手能够与在模拟器中运行的 iOS 应用进行可视化交互。
## 工作原理
该 MCP 服务器封装了 [Facebook 的 idb（iOS 开发桥）](https://github.com/facebook/idb)，以提供对 iOS 模拟器的隔离、无头控制。与控制鼠标/键盘的方法不同，idb 直接将触摸事件注入模拟器：
- **在后台运行** - 不会占用您的屏幕
- **隔离** - 您可以在它运行时使用计算机
- **可靠** - 使用与 Facebook 用于测试的相同基础设施
## 要求
- **macOS** （仅 iOS 模拟器在 Mac 上运行）
- **Xcode**，已安装 iOS 模拟器
- **Node.js** 18+
- **idb** （通过以下步骤安装）
### 安装 idb
```bash
# 安装 idb-companion（守护进程）
brew tap facebook/fb
brew install idb-companion
# 安装 idb（Python CLI 客户端）
pip3 install fb-idb
```
## 安装
### 选项 1：从 npm 安装（推荐）
```bash
npm install -g ios-sim-mcp
```
### 选项 2：克隆并构建
```bash
git clone https://github.com/artmamedov/ios-sim-mcp.git
cd ios-sim-mcp
npm install
npm run build
```
## 与 Claude Code 一起使用
```bash
claude mcp add ios-sim -s user -- npx ios-sim-mcp
```
或者，如果从源代码安装：
```bash
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 → 查找可用的模拟器及其 UDID
boot_simulator(udid) → 启动您想要的模拟器
screenshot → 验证它正在运行，查看屏幕
```
### 2. 查找和点击 UI 元素
```
# 选项 A：按标签搜索（推荐）
find_elements(label: "Sign In") → 返回具有匹配标签的元素
tap_element(label: "Sign In") → 查找并点击一步到位
# 选项 B：使用可访问性树中的坐标
describe_screen → 获取所有具有框架坐标的元素
tap(x: 196, y: 425) → 点击元素中心
```
### 3. 填写表单
```
tap_element(label: "Email") → 聚焦电子邮件字段
type_text(text: "user@test.com") → 输入电子邮件
press_key(key: "tab") → 移至下一个字段
type_text(text: "password123") → 输入密码
tap_element(label: "Submit") → 提交表单
```
### 4. 滚动和导航
```
# 向下滚动（向上滑动）
swipe(startX: 200, startY: 600, endX: 200, endY: 200)
# 向上滚动（向下滑动）
swipe(startX: 200, startY: 200, endX: 200, endY: 600)
# 返回主屏幕
press_button(button: "home")
```
### 5. 测试深链接
```
open_url(url: "myapp://profile/settings") → 打开自定义 URL 方案
screenshot → 验证加载正确的屏幕
```
## 可用工具
### 模拟器管理
| 工具 | 描述 | 返回 |
|------|-------------|---------|
| `list_simulators` | 列出所有 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` | 按设备按钮（home, lock, siri, apple_pay） | 确认字符串 |
### 应用管理
| 工具 | 描述 | 返回 |
|------|-------------|---------|
| `list_apps` | 列出已安装的应用 | 应用列表，包含包 ID |
| `launch_app` | 通过包 ID 启动应用 | 确认字符串 |
| `terminate_app` | 终止正在运行的应用 | 确认字符串 |
| `open_url` | 打开 URL（http 或自定义方案） | 确认字符串 |
## 元素发现
`describe_screen` 工具以以下格式返回 UI 元素：
```json
[
{
"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 │ （此服务器） │ CLI │ （Facebook 的） │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ iOS 模拟器 │
│ （Xcode） │
└─────────────────┘
```
## 配置
服务器在以下位置查找 `idb`：
1. `IDB_PATH` 环境变量（如果设置）
2. `~/Library/Python/3.9/bin/idb`
3. `/opt/homebrew/bin/idb`
4. `/usr/local/bin/idb`
5. 系统 PATH
## 故障排除
### "没有找到已启动的模拟器"
使用 `list_simulators` 查找可用的模拟器，然后使用 UDID 启动 `boot_simulator`。
### "未找到 idb"
安装 idb：`pip3 install fb-idb`
### "没有连接的 Companion"
idb companion 通常会自动启动。如果问题仍然存在：
```bash
idb_companion --udid <simulator-udid>
```
### 点击未命中正确元素
1. 坐标必须为 **点**，而非像素
2. 使用 `describe_screen` 获取确切的元素框架
3. 使用 `tap_element` 和元素的标签进行更可靠的点击
### 元素未找到标签
1. 使用 `describe_screen` 查看所有可用的标签
2. 标签是大小写不敏感的部分匹配
3. 某些元素可能未设置可访问性标签
## 许可证
MIT
## 致谢
- [Facebook idb](https://github.com/facebook/idb) - 底层自动化框架
- [Model Context Protocol](https://modelcontextprotocol.io/) - 协议规范
