xcode-mcp

MCP（模型上下文协议）服务器提供与 Xcode 相关的操作工具，方便用户通过 Claude Desktop 等 MCP 客户端处理 Xcode 项目。该服务器提供各种实用程序，用于 Xcode 项目管理、构建、测试、归档、代码签名以及相关的 iOS 开发工具。

特征

• Xcode 项目信息检索和方案列表
• 通过干净和自定义的输出选项增强构建功能
• 全面的测试执行和精细的控制
• 应用程序存档和 IPA 导出以供分发
• 代码签名和配置文件管理
• Swift 包管理器集成
• 通过 simctl 管理 iOS 模拟器
• 新功能：真实设备应用程序部署和启动，自动检测 Xcode 安装并改进设备管理
• 通过自动重试智能处理应用安装失败
• 智能缓存设备和 Xcode 信息以获得更好的性能

安装

用法

与 Claude Desktop 一起使用

1. 打开 Claude Desktop 配置文件：
   # macOS open ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. 添加或修改以下配置：
   { "mcpServers": { "xcode-mcp": { "command": "npx", "args": [ "@devyhan/xcode-mcp", "-y" ] } } }
3. 重新启动 Claude Desktop。

可用工具

1. xcode-项目信息

检索有关 Xcode 项目或工作区的详细信息，包括目标、配置和方案。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径

例子：

示例输出：

2. xcode-list-schemes

提供 Xcode 项目或工作区中所有可用方案、目标和配置的综合列表。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径

例子：

示例输出：

3. xcode 构建

使用增强选项构建 Xcode 项目或工作区。支持工作区和项目构建、全新构建以及自定义输出目录。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径
• scheme （必需）：要构建的方案
• configuration （可选）：构建配置（例如，调试、发布）
• destination （可选）：构建目标（例如，“platform=iOS Simulator，name=iPhone 14”）
• extraArgs （可选）：作为字符串数组的附加 xcodebuild 参数
• outputDir （可选）：自定义构建输出目录（SYMROOT）
• clean （可选）：是否执行干净构建（默认值：false）

例子：

生成的命令：

4. xcode 测试

使用丰富的选项为 Xcode 项目或工作区运行测试。提供对测试执行的细粒度控制，包括运行特定测试、测试计划和各种测试模式。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径
• scheme （必需）：要测试的方案
• destination （必填）：测试目的地（例如，“platform=iOS Simulator，name=iPhone 14”）
• testPlan （可选）：要使用的测试计划的名称
• onlyTesting （可选）：要运行的特定测试标识符数组
• skipTesting （可选）：要跳过的测试标识符数组
• resultBundlePath （可选）：保存测试结果包的路径
• buildForTesting （可选）：仅为测试而构建，不运行测试
• testWithoutBuilding （可选）：无需构建即可运行测试

例子：

生成的命令：

5. xcode-archive

创建 Xcode 项目的存档 (.xcarchive)，并可选择将其导出为 IPA 文件进行分发。通过导出选项 plist 支持 App Store、ad-hoc 和企业分发方式。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径
• scheme （必需）：要存档的方案
• configuration （可选）：构建配置（例如，发布）
• archivePath （必需）：保存 .xcarchive 文件的路径
• exportPath （可选）：导出档案的路径（例如 IPA 文件）
• exportOptionsPlist （可选）：exportOptions.plist 文件的路径

例子：

生成的命令：

6. xcode-codesign-info

检索 Xcode 项目的全面代码签名和配置文件信息。显示系统中已安装的代码签名标识、项目代码签名设置和配置文件。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径
• target （可选）：具体目标名称

例子：

示例输出：

7. swift 包管理器

提供对 Swift 包管理器 (SPM) 功能的访问，用于管理 Swift 包。支持 init、update、resolve、reset 和 clean 等常用 SPM 命令。

参数：

• command （必需）：要执行的 SPM 命令（“init”、“update”、“resolve”、“reset”、“clean”）
• packageDir （必需）：Swift 包的目录路径
• extraArgs （可选）：作为字符串数组的附加 SPM 参数

例子：

生成的命令：

示例输出：

8. simctl 管理器

通过simctl命令行工具提供对 iOS 模拟器管理功能的访问。支持列出、创建、启动、安装应用程序以及管理模拟器设备。

参数：

• command （必需）：SimCtl 命令（“列表”、“创建”、“启动”、“关机”、“擦除”、“安装”、“启动”、“删除”）
• extraArgs （可选）：作为字符串数组的附加 simctl 参数

例子：

生成的命令：

示例输出（缩写） ：

9. 在设备上运行

在实体 iOS 设备上构建、安装并运行应用。支持使用设备名称（包括韩文名称）或 UUID 进行设备选择、环境变量和日志流传输。现支持直接指定 bundleId、跳过构建选项以及其他启动参数。

参数：

• projectPath （必需）：Xcode 项目（.xcodeproj）或工作区（.xcworkspace）的路径
• scheme （必需）：要构建和运行的方案
• device （必填）：设备标识符或名称（支持韩文名称）
• configuration （可选）：构建配置（例如，调试、发布）
• streamLogs （可选）：启动后是否流式传输设备日志
• startStopped （可选）：是否在暂停状态下启动应用程序以进行调试器连接
• environmentVars （可选）：传递给应用程序的环境变量（key1=value1,key2=value2 格式）
• xcodePath （可选）：Xcode 应用程序路径（默认值：“/Applications/Xcode-16.2.0.app”）
• listDevices （可选）：运行前显示所有检测到的设备及其 ID
• skipBuild （可选）：跳过已安装应用程序的构建和安装步骤
• extraLaunchArgs （可选）：传递给 devicectl launch 命令的附加参数
• directBundleId （可选）：直接指定 bundle ID，而不是从项目中提取

例子：

过程：

1. 该工具可识别指定设备的 Xcode UDID 和 CoreDevice UUID
2. 它使用 Xcode UDID 来构建和安装应用程序
3. 它使用 CoreDevice UUID 通过devicectl启动应用程序
4. 它检索应用程序的包标识符
5. 如果需要，它会传输设备日志

v0.4.0 中的关键改进：

• 无需项目即可直接指定 bundleId
• 跳过已安装应用程序的构建和安装步骤
• 支持额外的 devicectl 启动命令参数
• 更好的设备型号和操作系统版本信息显示
• 改进了 devicectl 命令的路径处理和日志记录

示例输出：

示例场景：与 LLM 一起使用

下面是一个示例，说明如何提示像 Claude 这样的法学硕士按顺序使用这些工具：

用户提示 Claude：

预期工作流程：

1. Claude 将执行xcode-list-schemes工具来检索所有方案：
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
2. Claude 将使用已识别的方案执行xcode-test工具：
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: [First scheme from output] Destination: platform=iOS Simulator,name=iPhone 14
3. 然后，Claude 将使用xcode-archive工具创建一个档案：
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: [First scheme from output] Configuration: Release ArchivePath: /Users/username/Desktop/MyApp.xcarchive

此工作流程演示了如何将多个工具链接在一起，使用一个工具的输出来通知另一个工具的参数。

示例：在真实设备上运行

用户提示 Claude：

预期工作流程：

1. Claude 首先会获取设备列表：
   listDevices: true
2. Claude 将识别您的物理设备并在其上运行该应用程序：
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: MyApp Device: "Your iPhone" (or the device UUID) StreamLogs: true
3. 无需重建即可快速重新启动：
   Device: "Your iPhone" DirectBundleId: "com.example.myapp" SkipBuild: true

安全注意事项

此工具可执行Xcode相关命令，存在安全风险，请注意：

• 仅与受信任的 Xcode 项目一起使用。
• 对来源不明的项目要谨慎。
• 不要在构建参数中包含敏感信息。

发展

要求

• Node.js 16 或更高版本
• npm 6 或更高版本
• Xcode 14 或更高版本（适用于所有功能）
• Xcode 16 或更高版本（ devicectl和真实设备功能所需）

本地开发和测试

执照

麻省理工学院