AI导哈

iOS模拟器控制工具

一个通过MCP协议控制Xcode iOS模拟器的开源工具，支持点击、滑动、输入、屏幕描述和启动应用等功能。

  • by HayaoAkiyama
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 HayaoAkiyama/sim-mcp

使用说明

sim-mcp

一个MCP（模型上下文协议）服务器，允许AI代理通过标准MCP工具控制Xcode iOS模拟器——点击、键入、滑动、读取屏幕、启动应用程序。

作为开源替代品构建 镜子 iOS模拟器。MCP SDK之外的零外部依赖性-仅使用macOS本机API。

运作原理

Claude Code / MCP Client
        │
        │  MCP protocol (stdio, JSON-RPC)
        ▼
   ┌─────────┐
   │ server.py│  ← FastMCP tool definitions (16 tools)
   └────┬─────┘
        │
        ▼
┌──────────────┐
│ sim_control.py│  ← Core engine
└──┬───┬───┬───┘
   │   │   │
   │   │   └── xcrun simctl ─── screenshots, app launch, URLs, clipboard
   │   │
   │   └── CoreGraphics CGEvent (ctypes) ─── tap, swipe, type, keyboard
   │
   └── Apple Vision framework (Swift OCR helper, compiled on first use) ─── describe_screen

核心不需要pip包。 sim_control.py 通过Python仅使用macOS系统框架独立工作 ctypesThe mcp 仅MCP服务器包装器需要此包。

需求

  • macOS（在macOS 15 Sequoia上测试）
  • 安装了iOS模拟器的Xcode
  • Python 3.10+（推荐使用Python 3.12）
  • 已启动的iOS模拟器(xcrun simctl boot <device>)

快速开始

1.克隆和设置

git clone https://github.com/HayaoAkiyama/sim-mcp.git
cd sim-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2.启动模拟器

# List available devices
xcrun simctl list devices available

# Boot one (e.g., iPhone 16 Pro)
xcrun simctl boot "iPhone 16 Pro"

# Open the Simulator app so the window is visible
open -a Simulator

3.用克劳德代码注册

添加到您的项目 .mcp.json （或在项目根目录中创建一个）：

{
  "mcpServers": {
    "sim": {
      "command": "/path/to/sim-mcp/.venv/bin/python3",
      "args": ["/path/to/sim-mcp/server.py"]
    }
  }
}

重新启动克劳德代码。工具将显示为 mcp__sim__tap, mcp__sim__screenshot等等。

4.或用作CLI

sim_control.py 也可以作为一个独立的命令行工具，而不需要MCP服务器：

python3 sim_control.py screenshot /tmp/screen.png
python3 sim_control.py tap 200 400
python3 sim_control.py type "Hello world"
python3 sim_control.py describe
python3 sim_control.py launch com.apple.mobilesafari
python3 sim_control.py home
python3 sim_control.py swipe 200 600 200 200
python3 sim_control.py status

工具

工具 参数 说明
screenshot -- 以base64 PNG格式捕获屏幕
describe_screen —— OCR屏幕；返回带有点击坐标的文本元素
get_orientation -- 退货 "portrait" 或 "landscape"
tap x, y 点击设备点坐标
double_tap x, y 双击（选择文本，缩放）
long_press x, y, duration_ms 长按（上下文菜单，拖动模式）
type_text text 在焦点字段中键入文本
swipe from_x/y, to_x/y, duration_ms 快速滑动手势
drag from_x/y, to_x/y, duration_ms 缓慢拖动（重新排序项目）
scroll_to direction, amount 从中心向上/向下/向左/向右滚动
press_home -- 转到主屏幕
press_key key, modifiers 使用修饰符按任意键
launch_app identifier 按捆绑包ID或应用程序名称启动
open_url url 在Safari中打开URL
status -- 设备信息和坐标映射
check_health -- 验证模拟器是否正在运行

坐标系

所有坐标均在 设备点 （非像素），带 (0, 0) 在设备屏幕的左上角。

设备 宽度 高度 比例
iPhone 16 Pro 402 874 3倍
iPhone 16 393 852 3x
iPhone SE 375 667 2x
iPad Pro 13英寸 1024 1366 2x

控制器自动检测启动模拟器的尺寸。

典型工作流程

1. describe_screen  →  find UI elements and their coordinates
2. tap(x, y)        →  tap a button/field at the OCR coordinates
3. type_text("...")  →  enter text into the focused field
4. screenshot       →  verify the result

建筑

sim_control.py——核心引擎

输入（点击、滑动、键入）： 用途 CoreGraphics CGEvent 通过Python ctypes 将合成鼠标和键盘事件直接发布到macOS事件系统。模拟器窗口接收这些事件，就像它们来自真实的鼠标/键盘一样。

坐标映射： 在init上，查询模拟器窗口的 AXGroup （设备屏幕视图）通过macOS Accessibility API获取其确切的屏幕位置和大小。地图设备点坐标→ macOS屏幕坐标使用从AXGroup大小和设备像素尺寸导出的比例因子。

文本输入： 通过CGEvent按键逐一键入字符。处理大写字母（Shift标志）、符号（Shift+基本键），并为不在美国键盘布局中的Unicode字符回退到剪贴板粘贴。

OCR（describe_secreen）： 编译Swift助手(/tmp/sim_ocr)首次使用运行苹果Vision框架 VNRecognizeTextRequest。返回具有像素坐标的文本边界框，并将其转换为设备点。

屏幕截图： 用途 xcrun simctl io <udid> screenshot 用于像素完美的设备截图（无窗口chrome）。

server.py--MCP包装器

薄包装使用 MCP Python SDKs FastMCP 类。每个工具都是一个装饰功能，委托给 SimController.使用JSON-RPC 2.0通过stdio进行通信。

故障排除

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

先启动模拟器： xcrun simctl boot "iPhone 16 Pro" 并打开模拟器应用程序： open -a Simulator.

文本输入产生日语/错误字符

模拟器的iOS键盘必须设置为英语。通过重置键盘首选项进行修复：

UDID=$(xcrun simctl list devices booted -j | python3 -c "import sys,json; d=json.load(sys.stdin); print([x['udid'] for v in d['devices'].values() for x in v if x['state']=='Booted'][0])")

xcrun simctl spawn $UDID defaults write -g AppleKeyboards -array "en_US@sw=QWERTY;hw=Automatic"
xcrun simctl spawn $UDID defaults write -g ApplePasscodeKeyboards -array "en_US@sw=QWERTY;hw=Automatic" "emoji@sw=Emoji"
xcrun simctl spawn $UDID defaults write com.apple.keyboard.preferences KeyboardLastUsed -string "en_US@sw=QWERTY;hw=Automatic"
xcrun simctl spawn $UDID launchctl stop com.apple.SpringBoard

水龙头落在错误的地方

跑 python3 sim_control.py calibrate 点击四个角和中心。如果抽头偏移，则模拟器窗口可能已调整大小——控制器在每次初始化时都会重新计算几何体。

必须启用“连接硬件键盘”

在模拟器菜单中： I/O>键盘>连接硬件键盘 （应检查）。这允许CGEvent键盘事件到达iOS。

许可证

麻省理工学院

相关 MCP