AI导哈

iOS模拟器控制协议

iossim-mcp是一个通过XCUITest控制iOS模拟器应用的MCP（Model Context Protocol）服务器，提供模拟器控制、应用管理、UI自动化等功能。

  • by hiragram
  • Swift
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 hiragram/iossim-mcp

使用说明

iossim mcp

一个MCP（模型上下文协议）服务器，用于通过XCUITest控制iOS模拟器应用程序。

特性

  • 模拟器控制：启动、关闭和管理iOS模拟器
  • 应用程序管理：在模拟器上启动和终止应用程序
  • UI自动化：在引擎盖下使用XCUITest点击、滑动、键入文本
  • 截图：捕获模拟器屏幕截图
  • 无需修改应用程序：使用可以控制任何应用程序的通用XCUITest驱动程序

需求

  • macOS 14.0+
  • Xcode 26.0+（带iOS模拟器）
  • Swift 6.2+

安装

使用swx（推荐）

添加到MCP配置中：

{
  "mcpServers": {
    "iossim": {
      "command": "swx",
      "args": ["hiragram/iossim-mcp"]
    }
  }
}

可用工具

模拟器控制

工具 说明
list_simulators 列出所有可用的iOS模拟器
boot_simulator 通过UDID启动iOS模拟器
shutdown_simulator 通过UDID关闭iOS模拟器

应用程序管理

工具 说明
launch_app 在模拟器上启动应用程序
terminate_app 在模拟器上终止应用程序

UI自动化

工具 说明
tap 通过可访问性标识符或标签点击元素
type_text 在元素或焦点字段中键入文本
swipe 向上/下/左/右方向滑动
run_ui_script 运行一系列UI操作

截图

工具 说明
take_screenshot 截取模拟器的屏幕截图

使用示例

列出可用模拟器

{
  "tool": "list_simulators"
}

启动模拟器并启动应用程序

{
  "tool": "boot_simulator",
  "arguments": {
    "udid": "DF27CC78-36A5-44D0-AF24-60555158BDB8"
  }
}

{
  "tool": "launch_app",
  "arguments": {
    "bundleId": "com.example.myapp"
  }
}

点击按钮

{
  "tool": "tap",
  "arguments": {
    "bundleId": "com.example.myapp",
    "identifier": "login_button"
  }
}

在字段中键入文本

{
  "tool": "type_text",
  "arguments": {
    "bundleId": "com.example.myapp",
    "text": "hello@example.com",
    "identifier": "email_field"
  }
}

执行一系列操作

{
  "tool": "run_ui_script",
  "arguments": {
    "bundleId": "com.example.myapp",
    "actions": [
      { "type": "tap", "target": { "type": "identifier", "value": "email_field" } },
      { "type": "typeText", "text": "user@example.com" },
      { "type": "tap", "target": { "type": "identifier", "value": "password_field" } },
      { "type": "typeText", "text": "secretpassword" },
      { "type": "tap", "target": { "type": "identifier", "value": "login_button" } },
      { "type": "waitForElement", "target": { "type": "identifier", "value": "home_screen" }, "timeout": 10 }
    ]
  }
}

动作类型 run_ui_script

操作 属性
tap target （必填）
typeText text （必填）， target （可选）
swipe direction （必填：上/下/左/右）， target （可选）
longPress target （必填）， duration （可选，秒）
waitForElement target （必填）， timeout （可选，秒）
assertExists target （必填）
screenshot outputPath （可选）

目标规范

// By accessibility identifier
{ "type": "identifier", "value": "my_button" }

// By label text
{ "type": "label", "value": "Submit" }

// By screen coordinates
{ "type": "coordinate", "x": 100, "y": 200 }

建筑

┌─────────────────────────────────────────────────────────────┐
│                      MCP Client (Claude, etc.)              │
└─────────────────────────────────────────────────────────────┘
                              │ stdio
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     iossim-mcp (executable)                  │
│  - MCP Server (modelcontextprotocol/swift-sdk)              │
│  - Tool handlers                                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Core (library)                           │
│  - SimulatorController: simctl wrapper                       │
│  - UITestDriver: xcodebuild test-without-building            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              SimDriverUITests (bundled XCUITest)             │
│  - Generic test driver                                       │
│  - Reads JSON script, executes XCUITest actions              │
│  - Writes results to JSON                                    │
└─────────────────────────────────────────────────────────────┘

发展

运行测试

swift test

重建UITest驱动程序

如果你修改 SimDriverHost/SimDriverUITests/DriverTests.swift:

cd SimDriverHost
xcodebuild -project SimDriverHost.xcodeproj \
  -scheme SimDriverUITests \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  build-for-testing

# Copy the built artifacts
cp -R ~/Library/Developer/Xcode/DerivedData/SimDriverHost-*/Build/Products/Debug-iphonesimulator/SimDriverUITests-Runner.app \
  ../Sources/iossim-mcp/Resources/

cp ~/Library/Developer/Xcode/DerivedData/SimDriverHost-*/Build/Products/*.xctestrun \
  ../Sources/iossim-mcp/Resources/

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

相关 MCP