Xctools MCP Server

XCTools MCP服务器

一个模型上下文协议（MCP）服务器，提供对Xcode开发工具的结构化访问，包括 xcrun, xcodebuild，以及 xctrace.

安装

方法1：使用uvx

1. 先决条件:

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

1. 直接用uvx运行:

   uvx xctools-mcp-server

方法2：本地开发安装

1. 先决条件:

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

1. 克隆并安装:

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

1. 运行服务器:

   xctools-mcp-server

方法3：从源代码构建

1. 制造轮子:

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

配置

适用于克劳德桌面

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

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

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

或者如果使用uvx：

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

1. 重新启动VS代码 加载MCP服务器
2. 使用命令选项板 (Cmd+Shift+P)并搜索“MCP”命令以与Xcode开发工具交互

对于其他MCP客户端

服务器在stdio上运行，因此您可以直接调用它：

安装软件包后：

xctools-mcp-server

使用uvx：

uvx xctools-mcp-server

特性

• 完成Xcode工具链访问 通过 xcrun
• 项目建设和测试 随着 xcodebuild
• 性能分析 使用 xctrace （仪器）
• 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工具（仪器）

• xctrace_record -记录新仪器痕迹
• xctrace_import -将支持的文件导入跟踪格式
• xctrace_export -从跟踪文件导出数据
• xctrace_list -列出可用的设备、模板或仪器
• 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"

仪器性能分析

# 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命令行工具何时不可用
• 无效参数：验证工具参数并提供有用的错误消息
• 工具可用性：执行前检查所需工具

故障排除

常见问题

1. “xcrun:错误：找不到实用程序”

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

1. “找不到开发人员目录”

- 从Mac应用商店安装Xcode - 接受Xcode许可证： sudo xcodebuild -license accept

1. 权限错误

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

1. 工具未找到错误

- 验证Xcode安装中是否提供了特定工具 - 某些工具可能需要特定的Xcode版本或附加组件

需求

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

贡献

欢迎投稿！请随时提交拉取请求。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

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

安全考虑

• 服务器仅公开读取和模拟器管理操作
• 无法访问指定应用程序路径之外的主机文件系统
• 推送通知有效载荷的结构得到验证
• 隐私权限更改是明确的并记录在案的

开发说明

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