/ 目录 / 演练场 / XcodeBuild
← 全部服务器 ↗ GitHub
● 官方 getsentry ⚡ 即开即用

XcodeBuild

作者 getsentry · getsentry/XcodeBuildMCP

在聊天中闭合 iOS/macOS AI 编码反馈循环——构建、测试、模拟器运行、捕获日志和截图，一切尽在聊天。

XcodeBuildMCP（由 Sentry 前员工 Cameron 开发）封装了 xcodebuild、xcrun simctl 和模拟器运行时。它让 agent 能够编译项目、运行测试、启动模拟器、安装应用、控制应用，以及读取日志或截图——这是 AI 生成 iOS 代码所缺失的反馈循环。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

xcodebuild.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "xcodebuild",
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "xcodebuild": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "xcodebuildmcp@latest"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add xcodebuild -- npx -y xcodebuildmcp@latest

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： XcodeBuild

验证 AI 生成的 iOS 代码能否正确构建并在模拟器中运行

👤 使用 Claude 进行功能开发和 SwiftUI 原型开发的 iOS 开发者 ⏱ ~15 min intermediate

何时使用： Claude 刚刚编写或编辑了 SwiftUI 视图。在说'完成'之前，你想编译、在模拟器上运行并截图。

前置条件
  • Xcode 已安装 — 从 Mac App Store 安装 Xcode 15+；用 xcodebuild -version 确认
  • 可启动的模拟器 — Xcode → Settings → Platforms → 下载 iOS Simulator
步骤
  1. 发现项目并构建
    在 /Users/me/Projects/MyApp 中查找 Xcode 项目。为 iOS Simulator destination 'iPhone 16' 构建 scheme 'MyApp'。报告任何错误或警告。✓ 已复制
    → 构建成功，或显示包含 file:line 的具体错误
  2. 启动模拟器、安装、启动应用
    启动 iPhone 16 模拟器（如果尚未启动）。安装构建的应用并启动。3 秒后截图。✓ 已复制
    → 应用运行；截图已捕获
  3. 驱动功能
    点击'Sign Up'按钮，在邮箱字段输入'[email protected]'，点击提交。每一步后截图。✓ 已复制
    → 显示流程的一系列截图；或清晰的点击失败错误

结果： 证明功能有效的前后对比截图，与代码一起提交。

注意事项
  • 按坐标点击在不同设备尺寸上容易出问题 — 当 MCP 支持时，优先使用基于 accessibility-label 的点击；仅在必要时使用坐标
  • 模拟器构建使用的架构与真实设备不同 — 对于架构敏感的代码，在合并前至少构建一次真实设备版本
搭配使用： filesystem · github

在聊天中运行 Xcode 单元和 UI 测试并分类故障

👤 希望快速获得测试反馈而不切换到 Xcode 的 iOS 开发者 ⏱ ~10 min beginner

何时使用： 你进行了更改，想运行 ⌘U 的等价命令，并让 Claude 分析失败。

步骤
  1. 运行测试
    在 destination 'iPhone 16' 上运行 scheme 'MyApp' 的所有测试。显示任何包含文件、行号和预期的失败。✓ 已复制
    → 通过数量加上带位置的失败列表
  2. 专注一个失败
    对于第一个失败，读取源文件并告诉我是测试错误还是代码错误。要具体。✓ 已复制
    → 清晰的诊断，不是'可能两者都是'
  3. 修复并重新运行
    应用修复。仅重新运行失败的测试以确认通过。✓ 已复制
    → 重新运行通过

结果： 通过有针对性的重新运行让测试恢复绿色，而不是全套重新运行。

注意事项
  • xcodebuild test 在冷缓存上很慢 — 使用 -only-testing: 标志缩小范围；MCP 通过 test-by-identifier 公开这个功能
搭配使用： github

诊断神秘的 Xcode 构建错误

👤 遇到'链接错误 / 缺少框架 / 签名'问题的 iOS 开发者 ⏱ ~20 min intermediate

何时使用： xcodebuild 失败，错误输出是 4000 行噪音。

步骤
  1. 构建并捕获原始失败
    构建 scheme 'MyApp'，仅返回包含 'error:' 或 'warning:' 的行，加上每行周围的 3 行上下文。✓ 已复制
    → 没有噪音的有针对性的错误列表
  2. 解释第一个错误
    用人类语言解释第一个错误。Xcode 实际上在抱怨什么，前 3 个原因是什么？✓ 已复制
    → 用普通英文诊断加上可能的原因
  3. 应用修复并重新构建
    应用最可能的修复（根据需要检查 Info.plist/entitlements/Package.swift），重新构建，并确认错误已消失。✓ 已复制
    → 清晰的构建

结果： 从构建障碍中解脱，而不需花 2 小时在 Stack Overflow 兔子洞里。

注意事项
  • 有些错误是 DerivedData 过期 — 万不得已时：通过 MCP 的 clean 工具清理 DerivedData，然后重新构建
搭配使用： filesystem

捕获模拟器上的应用崩溃并找到根本原因

👤 追踪可重现崩溃的 iOS 开发者 ⏱ ~20 min advanced

何时使用： 你的应用在模拟器上的特定流程中崩溃，你想让 Claude 读取崩溃日志。

步骤
  1. 通过日志捕获重现
    在 iPhone 16 模拟器上启动 MyApp。开始日志捕获。执行以下流程：打开 Settings，点击'Clear Cache'。应用崩溃时停止日志捕获。✓ 已复制
    → 崩溃已重现，日志已保存
  2. 解析崩溃
    在捕获的日志中找到崩溃。如需要则符号化。告诉我失败的线程、前 5 个堆栈帧，以及我们代码中可能的行。✓ 已复制
    → 符号化的堆栈跟踪指向特定源文件
  3. 提出修复
    根据堆栈跟踪和周围的代码，修复它的最小改动是什么？应用它。✓ 已复制
    → 有针对性的修复，不是大规模重构

结果： 修复的崩溃加上符号化证据，你可以粘贴到 PR 中。

注意事项
  • Release 配置崩溃没有 dSYM 时无法符号化 — 使用 Debug 配置重现；分别测试 Release 以确认修复
搭配使用： sentry · github

组合

与其他 MCP 搭配，撬动十倍杠杆

xcodebuild + filesystem

编辑 Swift → 构建 → 截图 → 迭代，全部在一个聊天中完成

编辑 ContentView.swift 添加暗色模式切换。为 iPhone 16 构建 MyApp，运行它，在浅色和暗色模式下各截一张图。✓ 已复制
xcodebuild + github

修复问题，在模拟器上验证，用截图打开 PR

Issue #42 说登录按钮在横屏时对齐不正确。在 iPad 模拟器上重现，修复 SwiftUI 布局，在 PR 中附上前后对比截图。✓ 已复制
xcodebuild + sentry

在模拟器上用相同条件重现 Sentry 报告的崩溃

Sentry crash iOS-113 发生在 iOS 18.1 上，用户区域设置为 fr-FR。启动匹配的模拟器，重现并修复。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
discover_projects directory: str 在不输入路径的情况下找到仓库中要构建的内容 free
build_project project: str, scheme: str, destination: str, configuration?: 'Debug'|'Release' 为 destination 构建 .xcodeproj 或 .xcworkspace free
build_spm_package path: str 构建 Swift Package（无 .xcodeproj） free
test_project project, scheme, destination, only_testing?: str[] 运行测试套件；使用 only_testing 缩小范围 free
list_simulators none 查看存在哪些模拟器以及哪些已启动 free
boot_simulator simulator_id or name: str 在安装应用前启动模拟器 free
install_app simulator_id: str, app_path: str 在启动的模拟器上安装构建的 .app free
launch_app simulator_id: str, bundle_id: str 启动已安装的应用 free
tap_at / type_text / send_url simulator params 驱动 UI free
screenshot simulator_id: str, path?: str 捕获视觉状态 free
start_log_capture / stop_log_capture simulator_id 为会话捕获控制台/系统日志 free
clean project, scheme? 当构建出现问题时清除该项目的 DerivedData free

成本与限制

运行它的成本

API 配额
无——所有内容都通过 xcodebuild/simctl 在本地运行
每次调用 Token 数
构建日志可能很大。优先过滤到错误/警告，而不是完整日志转储
费用
免费（需要带 Xcode 的 Mac，这本身就有成本）
提示
默认运行增量构建，不要清晰构建。仅当 DerivedData 出现问题时清理。

安全

权限、密钥、影响范围

凭据存储： MCP 层没有凭据。代码签名凭据像往常一样存储在你的 Mac 钥匙链中。
数据出站： MCP 无数据出口。xcodebuild 可能从通常来源获取依赖（SPM、CocoaPods）。
切勿授予： 不要让 agent 在未经确认的情况下修改代码签名身份或配置文件

故障排查

常见错误与修复

xcodebuild：命令未找到

Xcode Command Line Tools 缺失或未选择。运行 xcode-select --install，然后运行 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer。

验证： xcodebuild -version
没有这样的 destination 'iPhone 16'

具有该名称的模拟器未为活跃的 Xcode 下载。打开 Xcode → Settings → Platforms → 下载 iOS runtime。或使用 list_simulators 选择现有的。

验证： xcrun simctl list devices
构建成功但应用无法启动——'NSException'

在启动前通过 start_log_capture 检查应用日志。通常是 Info.plist 缺少键，或权限不匹配。

测试在 SwiftUI 预览上挂起

SwiftUI 预览在极少数情况下可能导致 xcodebuild test 死锁。禁用测试 schemes 中的预览助手，或使用 -disable-concurrent-testing 运行。

替代方案

XcodeBuild 对比其他方案

替代方案何时用它替代权衡
直接 shell MCP 运行 xcodebuild你想要最大灵活性并接受原始 shell MCP 的安全权衡没有人体工学；Claude 必须知道每个 xcodebuild 标志
JetBrains MCP（AppCode 已停止支持）你在 JetBrains IDE 中——不再适用于 iOS今天不是 iOS 的替代方案
通过 shell 的 Fastlane你需要签名构建和 TestFlight 上传，而不仅仅是模拟器验证重得多；超出内循环开发的范围

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills