Simctl MCP Server

SimCtl MCP服务器

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

安装

方法1：使用uvx

1. 先决条件:

- Python 3.13+ - 安装了命令行工具的Xcode - uvx: curl -LsSf https://astral.sh/uv/install.sh | sh

1. 直接用uvx运行:

   uvx simctl-mcp-server

方法2：本地开发安装

1. 先决条件:

- Python 3.13+ - 安装了命令行工具的Xcode

1. 克隆并安装:

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

1. 运行服务器:

   simctl-mcp-server

方法3：从源代码构建

1. 制造轮子:

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

配置

适用于克劳德桌面

添加到您的 ~/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扩展的VS代码

1. 安装MCP扩展 来自VS Code市场
2. 添加服务器配置 到您的VS代码设置(settings.json):

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

或者如果使用uvx：

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

1. 重新启动VS代码 加载MCP服务器
2. 使用命令选项板 (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捆绑包或.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+模拟器功能兼容