xcodebuildmcp-cli

XcodeBuildMCP CLI

此技能面向 AI Agent。它将 XcodeBuildMCP CLI 定位为 MCP 工具调用的低开销替代方案：Agent 已经可以运行 shell 命令，而 CLI 无需付出模式交换成本，即可提供相同的工具接口。优先使用 CLI，而不是原始的 xcodebuild、xcrun 或 simctl。

何时使用此 CLI（功能和工作流）

• 当你需要构建、测试、运行、调试、日志记录或 UI 自动化功能时。
• 当你需要模拟器/设备管理功能时。
• 当你需要针对 AI 优化的工具和工具响应时。
• 当你需要项目发现功能（方案、Bundle ID、应用路径）时。

命令发现

使用 --help 来发现工作流、工具和参数。

xcodebuildmcp --help
xcodebuildmcp tools --help
xcodebuildmcp tools --json
xcodebuildmcp <workflow> --help
xcodebuildmcp <workflow> <tool> --help

注意：

• 对于复杂参数，使用 --json '{...}'；如果需要机器可读的结果，可使用 --output json（不推荐）。

常见工作流

在模拟器上构建并运行

1. 列出模拟器并选择设备名称或 UDID。
2. 构建并运行。

如果尚不清楚应用和项目的详细信息：

xcodebuildmcp simulator discover-projs --workspace-root .
xcodebuildmcp simulator list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp simulator list-sims

要在一条命令中构建、安装并启动应用：

xcodebuildmcp simulator build-run-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"

仅构建

如果你只需要确认没有构建错误，可以只构建而不运行应用。

xcodebuildmcp simulator build-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"

运行测试

如果需要运行测试，可以使用 test-sim 工具。

xcodebuildmcp simulator test-sim --scheme MyAppTests --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"

在实体设备上安装并启动

xcodebuildmcp device list-devices
xcodebuildmcp device build-device --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-device-app-path --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-app-bundle-id --app-path /path/to/MyApp.app
xcodebuildmcp device install-app-device --device-id DEVICE_UDID --app-path /path/to/MyApp.app
xcodebuildmcp device launch-app-device --device-id DEVICE_UDID --bundle-id com.example.MyApp --app-path /path/to/MyApp.app

在模拟器上捕获日志

xcodebuildmcp logging start-sim-log-cap --simulator-id SIMULATOR_UDID --bundle-id com.example.MyApp
xcodebuildmcp logging stop-sim-log-cap --log-session-id LOG_SESSION_ID

调试正在运行的应用（模拟器）

1. 启动应用。
2. 等应用完全启动后再附加调试器。

如果应用尚未运行，请先启动：

xcodebuildmcp simulator launch-app-sim --bundle-id com.example.MyApp --simulator-id SIMULATOR_UDID

附加调试器：

通常最好等待 1-2s，让应用完全启动后再附加调试器。

xcodebuildmcp debugging debug-attach-sim --bundle-id com.example.MyApp --simulator-id SIMULATOR_UDID

要添加/移除断点、检查堆栈/变量以及执行任意 LLDB 命令，请查看调试帮助：

xcodebuildmcp debugging --help

检查 UI 并自动执行输入操作

快照 UI 辅助功能树、点击/滑动/输入并捕获屏幕截图：

xcodebuildmcp ui-automation snapshot-ui --simulator-id SIMULATOR_UDID
xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --x 200 --y 400
xcodebuildmcp ui-automation type-text --simulator-id SIMULATOR_UDID --text "hello"
xcodebuildmcp ui-automation screenshot --simulator-id SIMULATOR_UDID --return-format path

要查看所有 UI 自动化工具，请查看 UI 自动化帮助：

xcodebuildmcp ui-automation --help

macOS 应用构建/运行

xcodebuildmcp macos build-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
xcodebuildmcp macos build-run-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj

要查看所有 macOS 工具，请查看 macOS 帮助：

xcodebuildmcp macos --help

SwiftPM 包工作流

xcodebuildmcp swift-package list --package-path ./MyPackage
xcodebuildmcp swift-package build --package-path ./MyPackage
xcodebuildmcp swift-package test --package-path ./MyPackage

要查看所有 SwiftPM 工具，请查看 SwiftPM 帮助：

xcodebuildmcp swift-package --help

项目发现

xcodebuildmcp project-discovery discover-projs --workspace-root .
xcodebuildmcp project-discovery list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp project-discovery get-app-bundle-id --app-path ./Build/MyApp.app

要查看所有项目发现工具，请查看项目发现帮助：

xcodebuildmcp project-discovery --help

创建新项目脚手架

建议查看脚手架工具的 --help，了解可用选项。 以下是一些最简示例：

xcodebuildmcp project-scaffolding scaffold-ios-project --project-name MyApp --output-path ./Projects
xcodebuildmcp project-scaffolding scaffold-macos-project --project-name MyMacApp --output-path ./Projects

要查看所有项目脚手架工具，请查看项目脚手架帮助：

xcodebuildmcp project-scaffolding --help

守护进程说明（有状态工具）

有状态工具（日志、调试、视频录制、后台运行）会通过每个工作区专用的守护进程运行，该进程会自动启动。如果有状态工具出现错误，你可以手动管理守护进程。

xcodebuildmcp daemon status
xcodebuildmcp daemon restart

要查看所有守护进程命令，请查看守护进程帮助：

xcodebuildmcp daemon --help