Xcode Simctl

SimCtl MCP 服务

一个模型上下文协议（MCP）服务，通过 xcrun simctl 命令提供对 iOS 模拟器管理功能的结构化访问。

安装

方法 1：使用 uvx

1. 前置条件：

   • Python 3.13+
   • 已安装 Xcode 和 Command Line Tools
   • uvx：curl -LsSf https://astral.sh/uv/install.sh | sh

2. 使用 uvx 直接运行：

   uvx simctl-mcp-server
   

方法 2：本地开发安装

1. 前置条件：

   • Python 3.13+
   • 已安装 Xcode 和 Command Line Tools

2. 克隆并安装：

   git clone https://github.com/nzrsky/simctl-mcp-server
   cd simctl-mcp-server
   pip install .
   

3. 运行服务：

   simctl-mcp-server
   

方法 3：从源代码构建

1. 构建 wheel：

   python -m build --wheel
   pip install dist/simctl_mcp_server-0.1.0-py3-none-any.whl
   

配置

用于 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

或者使用 uvx：

{
  "mcpServers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}

用于搭配 MCP Extension 的 VS Code

1. 从 VS Code 市场安装 MCP Extension
2. 在 VS Code 设置中添加服务配置（settings.json）：

{
  "mcp.servers": {
    "simctl": {
      "command": "simctl-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

或者使用 uvx：

{
  "mcp.servers": {
    "simctl": {
      "command": "uvx",
      "args": ["simctl-mcp-server"],
      "env": {}
    }
  }
}

3. 重启 VS Code 以加载 MCP 服务
4. 使用命令面板（Cmd+Shift+P），搜索“MCP”命令以使用模拟器工具

用于其他 MCP 客户端

该服务通过 stdio 运行，因此可以直接调用：

使用已安装的软件包：

simctl-mcp-server

使用 uvx：

uvx simctl-mcp-server

可用工具

设备管理

• simctl_list_devices - 列出所有模拟器及其状态
• simctl_boot_device - 启动模拟器
• simctl_shutdown_device - 关闭模拟器
• simctl_create_device - 创建新的模拟器
• simctl_delete_device - 删除模拟器

应用管理

• simctl_install_app - 安装应用（.app bundle 或 .ipa）
• simctl_launch_app - 启动应用并指定选项
• simctl_terminate_app - 终止正在运行的应用

媒体和屏幕截图

• simctl_screenshot - 截取屏幕截图
• simctl_record_video - 录制视频（开始录制）

测试和开发

• simctl_push_notification - 发送推送通知
• simctl_privacy_control - 管理应用权限
• simctl_set_location - 设置设备位置/GPS
• simctl_status_bar_override - 覆盖状态栏外观
• simctl_ui_appearance - 控制浅色/深色模式

使用示例

基本设备操作

# List all devices
"List all available iOS simulators"

# Boot a specific device
"Boot the iPhone 15 Pro simulator"

# Create a new simulator
"Create a new iPhone 14 simulator named 'Test Device' with iOS 17.0"

应用测试

# Install and launch an app
"Install MyApp.app on the booted simulator and launch it"

# Take a screenshot
"Take a screenshot of the current simulator and save it to ~/Desktop/screenshot.png"

# Send a push notification
"Send a push notification with title 'Hello' and body 'Test message' to com.example.myapp"

UI 测试设置

# Set up a controlled testing environment
"Set the simulator to dark mode, override the status bar to show full battery and strong WiFi, and set the time to 9:41 AM"

# Grant permissions for testing
"Grant photo library access to com.example.myapp on the booted simulator"

位置测试

# Set specific location
"Set the simulator location to Apple Park (37.334606, -122.009102)"

# Clear location
"Clear the simulated location on the booted device"

错误处理

该服务包含全面的错误处理：

• 命令失败：返回 simctl 提供的详细错误信息
• 缺少 Xcode：检测 xcrun simctl 是否不可用
• 参数无效：执行前验证输入参数
• 文件操作：安全处理推送通知所需的临时文件

安全注意事项

• 该服务仅开放读取和模拟器管理操作
• 除指定的应用路径外，不会访问主机文件系统
• 会验证推送通知负载的结构
• 隐私权限变更需明确指定，并会记录日志

开发说明

• 专为 iOS 开发工作流构建
• 针对常见的模拟器管理任务进行了优化
• 对 JSON 响应进行结构化输出解析
• 支持单项和批量操作
• 兼容 Xcode 15+ 的模拟器功能