Xcode Instruments CLI

XCTools MCP 服务

一个 Model Context Protocol（MCP）服务，可通过结构化方式访问 Xcode 开发工具，包括 xcrun、xcodebuild 和 xctrace。

安装

方法 1：使用 uvx

1. 先决条件：

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

2. 使用 uvx 直接运行：

   uvx xctools-mcp-server
   

方法 2：本地开发安装

1. 先决条件：

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

2. 克隆并安装：

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

3. 运行服务：

   xctools-mcp-server
   

方法 3：从源代码构建

1. 构建 wheel：

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

配置

用于 Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

如果使用 uvx：

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

用于带 MCP 扩展的 VS Code

1. 从 VS Code Marketplace 安装 MCP 扩展
2. 将服务配置添加到 VS Code 设置（settings.json）：

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

如果使用 uvx：

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

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

用于其他 MCP 客户端

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

使用已安装的软件包：

xctools-mcp-server

使用 uvx：

uvx xctools-mcp-server

功能

• 通过 xcrun 完整访问 Xcode 工具链
• 使用 xcodebuild 构建和测试项目
• 使用 xctrace（Instruments）进行性能分析
• SDK 和目标设备管理
• 全面的错误处理，提供详细信息
• 跨平台兼容性（已安装 Xcode 的 macOS）

可用工具

XCRUN 工具

• xcrun_find_tool - 查找开发工具的路径（clang、swift 等）
• xcrun_show_sdk_path - 显示 SDK 的路径
• xcrun_show_sdk_version - 显示 SDK 版本
• xcrun_run_tool - 通过 xcrun 运行任意开发工具

XCODEBUILD 工具

• xcodebuild_build - 构建 Xcode 项目或工作区
• xcodebuild_test - 运行项目或工作区的测试
• xcodebuild_archive - 归档项目以供分发
• xcodebuild_list - 列出目标、方案和配置
• xcodebuild_show_sdks - 列出所有可用的 SDK
• xcodebuild_show_destinations - 显示有效的构建目标设备

XCTRACE 工具（Instruments）

• xctrace_record - 录制新的 Instruments 跟踪记录
• xctrace_import - 将受支持的文件导入跟踪记录格式
• xctrace_export - 从跟踪记录文件导出数据
• xctrace_list - 列出可用设备、模板或 Instruments
• xctrace_symbolicate - 使用调试符号对跟踪记录进行符号化

使用示例

查找开发工具

# Find the path to a specific tool
"Find the path to clang compiler"

# Show SDK path for iOS
"Show the path to the iOS SDK"

# Get SDK version information
"Show the version of the iOS SDK"

构建项目

# Build an Xcode project
"Build the project MyApp.xcodeproj for iOS simulator"

# Run tests for a workspace
"Run tests for MyApp.xcworkspace on iPhone 15 Pro simulator"

# Archive for distribution
"Archive MyApp.xcworkspace for release"

# List project information
"List all schemes and targets in MyApp.xcodeproj"

使用 Instruments 进行性能分析

# Record a trace for Time Profiler
"Record a Time Profiler trace for MyApp on iPhone 15 Pro for 30 seconds"

# List available instruments
"List all available Instruments templates"

# Export trace data
"Export data from trace file to XML format"

# Import a file for analysis
"Import a .dtps file into Instruments trace format"

SDK 和目标设备管理

# List all available SDKs
"Show all available SDKs for building"

# Show build destinations
"List all available destinations for iOS builds"

# Run a tool via xcrun
"Run swift command with version flag via xcrun"

错误处理

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

• 命令失败：返回 xcrun、xcodebuild 和 xctrace 提供的详细错误信息
• 缺少 Xcode：检测 Xcode Command Line Tools 是否不可用
• 参数无效：验证工具参数并提供实用的错误信息
• 工具可用性：执行前检查所需工具是否可用

故障排除

常见问题

1. "xcrun: error: unable to find utility"

   • 确保已安装 Xcode 命令行工具：xcode-select --install
   • 验证 Xcode 配置是否正确：xcode-select -p

2. "No developer directory found"

   • 从 Mac App Store 安装 Xcode
   • 接受 Xcode 许可协议：sudo xcodebuild -license accept

3. 权限错误

   • 确保用户拥有访问 Xcode 工具所需的权限
   • 尝试使用适当的 macOS 开发权限运行

4. 找不到工具错误

   • 确认 Xcode 安装中包含相应工具
   • 某些工具可能需要特定版本的 Xcode 或其他组件

要求

• macOS：必需（Xcode 开发工具仅适用于 macOS）
• Xcode：Xcode 命令行工具或完整的 Xcode 安装
• Python：3.13 或更高版本
• MCP 客户端：Claude Desktop、带有 MCP 扩展的 VS Code，或任何兼容 MCP 的客户端

贡献

欢迎贡献！欢迎提交拉取请求。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

• 无效参数：在执行前验证输入参数
• 文件操作：安全地处理推送通知的临时文件

安全注意事项

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

开发说明

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