xcode-mcp

一个 MCP (模型上下文协议) 服务器，提供与 Xcode 相关的操作工具，使从 MCP 客户端（如 Claude Desktop）处理 Xcode 项目更加容易。该服务器为 Xcode 项目管理、构建、测试、归档、代码签名和相关的 iOS 开发工具提供各种实用程序。

功能

• Xcode 项目信息检索和 scheme 列表
• 增强的构建能力，具有清理和自定义输出选项
• 具有精细控制的全面测试执行
• 用于分发的 App 归档和 IPA 导出
• 代码签名和配置描述文件管理
• Swift Package Manager 集成
• 通过 simctl 进行 iOS 模拟器管理
• 新增：真机 App 部署和启动，具有自动 Xcode 安装检测和改进的设备管理
• 智能处理 App 安装失败，自动重试
• 设备和 Xcode 信息的智能缓存，以获得更好的性能

安装

npm install @devyhan/xcode-mcp

用法

与 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-project-info

检索有关 Xcode 项目或工作区的详细信息，包括 targets、configurations 和 schemes。

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj

示例输出:

{
  "project": {
    "name": "MyApp",
    "targets": ["MyApp", "MyAppTests", "MyAppUITests"],
    "configurations": ["Debug", "Release"],
    "schemes": ["MyApp"]
  }
}

2. xcode-list-schemes

提供 Xcode 项目或工作区中所有可用 schemes、targets 和 configurations 的完整列表。

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj

示例输出:

Information about project "MyApp":
    Targets:
        MyApp
        MyAppTests
        MyAppUITests

    Build Configurations:
        Debug
        Release

    Schemes:
        MyApp
        MyAppTests

3. xcode-build

构建具有增强选项的 Xcode 项目或工作区。 支持工作区和项目构建、清理构建和自定义输出目录。

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径
• scheme (必需): 要构建的 scheme
• configuration (可选): 构建配置 (例如, Debug, Release)
• destination (可选): 构建目标 (例如, 'platform=iOS Simulator,name=iPhone 14')
• extraArgs (可选): 附加的 xcodebuild 参数，作为字符串数组
• outputDir (可选): 自定义构建输出目录 (SYMROOT)
• clean (可选): 是否执行清理构建 (默认: false)

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Configuration: Debug
Destination: platform=iOS Simulator,name=iPhone 14
Clean: true
OutputDir: /Users/username/Desktop/build

生成的命令:

xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" clean build -configuration "Debug" -destination "platform=iOS Simulator,name=iPhone 14" SYMROOT="/Users/username/Desktop/build"

4. xcode-test

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

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径
• scheme (必需): 要测试的 scheme
• destination (必需): 测试目标 (例如, 'platform=iOS Simulator,name=iPhone 14')
• testPlan (可选): 要使用的测试计划的名称
• onlyTesting (可选): 要运行的特定测试标识符数组
• skipTesting (可选): 要跳过的测试标识符数组
• resultBundlePath (可选): 保存测试结果包的路径
• buildForTesting (可选): 仅构建用于测试，不运行测试
• testWithoutBuilding (可选): 运行测试而不构建

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Destination: platform=iOS Simulator,name=iPhone 14
OnlyTesting: ["MyAppTests/LoginTests"]
ResultBundlePath: /Users/username/Desktop/TestResults

生成的命令:

xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" -destination "platform=iOS Simulator,name=iPhone 14" test -only-testing:"MyAppTests/LoginTests" -resultBundlePath "/Users/username/Desktop/TestResults"

5. xcode-archive

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

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径
• scheme (必需): 要归档的 scheme
• configuration (可选): 构建配置 (例如, Release)
• archivePath (必需): 保存 .xcarchive 文件的路径
• exportPath (可选): 导出归档的路径 (例如, IPA 文件)
• exportOptionsPlist (可选): exportOptions.plist 文件的路径

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Configuration: Release
ArchivePath: /Users/username/Desktop/MyApp.xcarchive
ExportPath: /Users/username/Desktop/Export
ExportOptionsPlist: /Users/username/Projects/MyApp/exportOptions.plist

生成的命令:

# Archive command
xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" -configuration "Release" archive -archivePath "/Users/username/Desktop/MyApp.xcarchive"

# Export command (if exportPath and exportOptionsPlist are provided)
xcodebuild -exportArchive -archivePath "/Users/username/Desktop/MyApp.xcarchive" -exportPath "/Users/username/Desktop/Export" -exportOptionsPlist "/Users/username/Projects/MyApp/exportOptions.plist"

6. xcode-codesign-info

检索 Xcode 项目的全面代码签名和配置描述文件信息。 显示系统上安装的代码签名身份、项目代码签名设置和配置描述文件。

参数:

• projectPath (必需): Xcode 项目 (.xcodeproj) 或工作区 (.xcworkspace) 的路径
• target (可选): 特定 target 名称

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Target: MyAppTarget

示例输出:

코드 서명 인증서 목록:
  1) 01AB2345CD6789EF0123456789ABCDEF01234567 "Apple Development: John Doe (ABC12DEF34)"
  2) 9876543210FEDCBA98765432109876543210FEDC "Apple Distribution: Example Corp (XYZ12ABC3)"

프로젝트 코드 서명 설정:
    CODE_SIGN_IDENTITY = Apple Development
    CODE_SIGN_STYLE = Automatic
    DEVELOPMENT_TEAM = ABC123DEF4
    PROVISIONING_PROFILE_SPECIFIER = 

설치된 프로비저닝 프로파일:
-rw-r--r--  1 username  staff  12345 Feb  1 12:34 01234567-89ab-cdef-0123-456789abcdef.mobileprovision
-rw-r--r--  1 username  staff  23456 Mar 15 09:12 fedcba98-7654-3210-fedc-ba9876543210.mobileprovision

7. swift-package-manager

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

参数:

• command (必需): 要执行的 SPM 命令 ("init", "update", "resolve", "reset", "clean")
• packageDir (必需): Swift Package 的目录路径
• extraArgs (可选): 附加的 SPM 参数，作为字符串数组

示例:

Command: update
PackageDir: /Users/username/Projects/MySwiftPackage
ExtraArgs: ["--enable-pubgrub-resolver"]

生成的命令:

cd "/Users/username/Projects/MySwiftPackage" && swift package update --enable-pubgrub-resolver

示例输出:

Resolving dependencies...
Fetching https://github.com/example/example-package.git
Checking out https://github.com/example/example-package.git at 1.2.3

8. simctl-manager

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

参数:

• command (必需): SimCtl 命令 ("list", "create", "boot", "shutdown", "erase", "install", "launch", "delete")
• extraArgs (可选): 附加的 simctl 参数，作为字符串数组

示例:

Command: list
ExtraArgs: ["devices", "--json"]

生成的命令:

xcrun simctl list devices --json

示例输出 (缩写):

{
  "devices": {
    "com.apple.CoreSimulator.SimRuntime.iOS-17-0": [
      {
        "name": "iPhone 14",
        "udid": "12345678-1234-1234-1234-123456789ABC",
        "state": "Booted",
        "isAvailable": true
      }
    ]
  }
}

9. run-on-device

在物理 iOS 设备上构建、安装和运行应用程序。 支持设备名称（包括韩语名称）或 UUID 用于设备选择、环境变量和日志流。 现在具有直接 bundleId 规范、跳过构建选项和附加启动参数。

参数:

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

示例:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Device: "Your-iPhone"
Configuration: Debug
StreamLogs: true
EnvironmentVars: "DEBUG_MODE=1,API_URL=https://test-api.example.com"

流程:

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

v0.4.0 中的主要改进:

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

示例输出:

// Standard output with build and install
앱 실행 결과:
Launched application with com.example.myapp bundle identifier.
로그 스트리밍이 시작되었습니다. 로그는 터미널에서 확인할 수 있습니다.

// Direct bundle ID usage with skip build
기기 모델: iPhone14,7
기기 OS 버전: 17.0
사용자 지정 번들 ID 사용: com.example.myapp
빌드 및 설치 과정 건너뛰기
앱 실행 결과:
Launched application with com.example.myapp bundle identifier.

示例场景：与 LLM 一起使用

以下是如何提示像 Claude 这样的 LLM 按顺序使用这些工具的示例：

用户提示 Claude:

I need to inspect my Xcode project, run some tests, and then archive it for distribution.

1. First, use the xcode-list-schemes tool to get all available schemes for my project at /Users/username/Projects/MyApp/MyApp.xcodeproj
2. After you see the schemes, run tests for the first available scheme on the iPhone 14 simulator.
3. Then archive the app for distribution using the Release configuration.

预期工作流程:

1. Claude 将执行 xcode-list-schemes 工具以检索所有 schemes：

   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
   

2. Claude 将使用已识别的 scheme 执行 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:

I need to test my app on a real device:

1. Get the list of available devices (including connected physical devices)
2. Run my app on my connected iPhone 

预期工作流程:

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 和真机功能需要）

本地开发和测试

# 克隆存储库
git clone https://github.com/devyhan/xcode-mcp.git
cd xcode-mcp

# 安装依赖项
npm install

# 在开发模式下运行
npm run dev

# 构建
npm run build

# 测试
npm test

许可证

MIT