getsentry/XcodeBuildMCP · 上手攻略

仓库：getsentry/XcodeBuildMCP
链接：https://github.com/getsentry/XcodeBuildMCP
分类：开发者工具 / MCP（Model Context Protocol）
作者：Tom
更新：2026-07-14

这是什么

XcodeBuildMCP 是 Sentry 团队开源的 Model Context Protocol（MCP）服务器 + CLI 工具，专为 AI 编码 agent（Cursor、Claude Code、Codex 等）设计，提供操作 iOS/macOS 项目的工具集——构建、运行、测试、安装应用到模拟器/设备等，全部通过结构化工具接口暴露给 AI。

它有两种使用模式：

MCP 服务器模式：作为 MCP 服务端，供支持 MCP 协议的 AI 客户端直接调用工具
独立 CLI 模式：直接用命令行操作 XcodeBuild，适合日常开发

一个安装包同时包含两种工具。

解决什么问题

在 AI Coding Agent 出现之前，自动化 iOS/macOS 构建需要写复杂的 shell 脚本，调用 xcodebuild 命令并解析输出。XcodeBuildMCP 把这些封装成了干净的、机器可读的 API 工具：

AI Agent 可以直接说「在 iPhone 16 Pro 模拟器上构建并运行我的 App」，而不用写 xcodebuild ... 命令行
支持构建配置切换、设备选择、scheme 管理、构建产物安装和启动
提供了 build_run_sim 等一键流工具，一个调用完成「构建 → 安装 → 启动 → 捕获日志」全流程
支持 MCP Skill（给 agent 的提示词模板）和 CLI Skill，降低 AI 理解 XcodeBuild 的门槛

快速安装

环境要求

macOS 14.5+
Xcode 16.x+
Node.js 18.x+（Homebrew 安装方式不需要单独装 Node）

方式一：Homebrew（推荐 macOS 用户）

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

方式二：npm（推荐有 Node.js 环境的用户）

npm install -g xcodebuildmcp@latest

验证安装

xcodebuildmcp --help

成功后会列出所有可用子命令。

核心用法

MCP 服务器模式（供 AI 客户端使用）

启动 MCP 服务器

xcodebuildmcp mcp

运行后服务器监听 MCP 协议端口，AI 客户端连接后即可调用工具。

配置 AI 客户端

官方文档提供了针对 Cursor、Claude Code、Codex 的配置示例，参考：https://xcodebuildmcp.com/docs/clients

大多数 MCP 客户端也支持直接用 npx 启动：

npx -y xcodebuildmcp@latest mcp

安装 Agent Skill（给 AI 的指令模板）

Skill 让 AI 更好地理解如何用 MCP 工具。有两种安装方式：

# 全局安装（安装到 ~/.xcodebuildmcp/）
xcodebuildmcp init

# npx 方式（不全局安装）
npx -y xcodebuildmcp@latest init

安装后会生成 Skill 配置文件，AI 在处理 Xcode 项目时会自动加载这些提示。

参考：https://xcodebuildmcp.com/docs/skills

独立 CLI 模式（日常开发）

列出可用工具

xcodebuildmcp tools

构建 iOS 项目（模拟器）

xcodebuildmcp simulator build \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj

一键构建 + 安装 + 运行（模拟器）

xcodebuildmcp simulator build-and-run \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj \
  --simulator-name "iPhone 16 Pro"

一键构建 + 安装 + 运行（真机）

⚠️ 真机需要 Xcode 中配置好代码签名（证书 + Provisioning Profile）

xcodebuildmcp device build-and-run \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj

设备相关文档：https://xcodebuildmcp.com/docs/device-signing

macOS App 构建

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

检查更新

xcodebuildmcp upgrade --check    # 检查是否有新版本
xcodebuildmcp upgrade --yes     # 自动升级

主要工具列表（82 个）

文档页面（https://xcodebuildmcp.com/docs/tools）实时从最新 release 拉取工具定义。以下是常用工具分类：

类别	代表工具	功能
模拟器构建	`simulator_build`	在模拟器上构建
模拟器运行	`build_run_sim`	构建 + 安装到模拟器 + 启动 + 捕获日志（一键流）
真机构建	`device_build`	在真机上构建
真机运行	`build_run_device`	构建 + 安装到真机 + 启动
macOS	`build_run_macos`	macOS App 一键构建运行
scheme 管理	`list_schemes`	列出项目中所有 scheme
日志	`fetch_simulator_logs`	获取模拟器日志
设备管理	`list_devices`	列出可用设备

📌 最常用：build_run_sim ——AI 需要你构建并跑 App 时，几乎都是这一个调用搞定。

典型适用场景

场景	说明
AI Coding Agent 开发 iOS App	AI 直接用自然语言控制构建、运行、调试
CI/CD 流水线	用 CLI 模式替代手写 `xcodebuild` 脚本，更可靠
自动化测试	`build_run_sim` 搭配测试框架自动跑 UITest
多设备兼容性验证	快速在不同模拟器上构建验证
Cursor/Claude Code 用户	开箱即用的 MCP 配置，AI 能直接操作 Xcode

坑与注意

macOS 14.5+ 和 Xcode 16.x+ 是硬性要求：旧版 macOS 或 Xcode 不支持，部分工具会直接报错。
真机工具需要代码签名配置：device build 和 build_run_device 需要 Xcode 中已配置好签名（证书 + Provisioning Profile），否则会失败。参考 Device Code Signing。
CLI 使用 daemon 机制：CLI 在执行「日志捕获」「调试」等有状态操作时会启动一个 per-workspace 后台守护进程，AI 工具调用时这个 daemon 会自动启动，用户无需手动管理。
Swift Macros 项目：XcodeBuildMCP 会让 xcodebuild 跳过宏验证，以避免使用 Swift Macros 的项目产生构建错误，这是设计行为而非 bug。
Sentry 遥测：XcodeBuildMCP 默认会收集少量内部运行时错误遥测数据（发送到 Sentry），仅用于改进产品，不会上传用户代码或项目内容。如需关闭：https://xcodebuildmcp.com/docs/privacy
模拟器名称空格问题：--simulator-name "iPhone 16 Pro" 如果名称有空格必须加引号。
npx 方式不走全局安装：每次 npx -y xcodebuildmcp@latest 会拉最新版本，但 daemon 状态文件可能不一致，建议还是全局安装。

与同类对比

工具	类型	AI Agent 适配	零配置	主要局限
XcodeBuildMCP	MCP Server + CLI	★★★★★ 原生 MCP	★★★★	仅 macOS
xcodebuild（原生）	CLI	需手写解析	★★★ 需写脚本	对 AI 不友好
Fastlane	CI/CD 工具链	需 prompt 工程	★★★	非 MCP，重量
Buddy	CI/CD 平台	不直接支持	★★	付费平台
MCP for Xcode（社区）	MCP Server	★★★★★	★★★	功能较基础

XcodeBuildMCP 是目前对 AI Coding Agent 支持最好的 Xcode 自动化工具，Sentry 团队维护，质量有保障。

一句话推荐结论

在 macOS 上做 iOS/macOS 开发且用 AI 编码助手（Cursor / Claude Code / Codex），装上 XcodeBuildMCP 就是最高效的接入方式——开箱即用的 MCP 协议支持，让 AI 直接用自然语言控制完整的构建-运行-调试流程。