一个模型上下文协议（MCP）服务器和命令行工具，为在 iOS 和 macOS 项目中工作的智能体提供辅助工具。

安装

XcodeBuildMCP 以单个软件包形式提供两种模式：一种是用于直接在终端使用的 CLI，另一种是面向 AI 编码智能体的 MCP 服务器。无论采用哪种安装方式，您都可以同时获得这两种模式。

选项 A — Homebrew

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

使用 CLI：

xcodebuildmcp --help

MCP 客户端配置：

"XcodeBuildMCP": {
  "command": "xcodebuildmcp",
  "args": ["mcp"]
}

后续升级时，运行 brew update && brew upgrade xcodebuildmcp。

选项 B — npm / npx（Node.js 18+）

仅用于 CLI，可全局安装：

npm install -g xcodebuildmcp@latest
xcodebuildmcp --help

仅用于 MCP 服务器，无需全局安装，直接添加到您的客户端配置中：

"XcodeBuildMCP": {
  "command": "npx",
  "args": ["-y", "xcodebuildmcp@latest", "mcp"]
}

如需锁定特定版本，将 @latest 替换为具体版本号（例如 xcodebuildmcp@1.0.0）。

客户端特定设置

以下示例使用 npx（选项 B）。如果您通过 Homebrew 安装，请将命令替换为 "command": "xcodebuildmcp", "args": ["mcp"]。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@latest mcp"
      ]
    }
  }
}

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

codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

"mcp": {
  "servers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

[mcp_servers.XcodeBuildMCP]
args = [
"-lc",
"PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
]
command = "/bin/zsh"
enabled = true
tool_timeout_sec = 10000

  // ... 文件其余部分 ...
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
      ]
    }
  }
}

/mcp add XcodeBuildMCP --command npx --args "-y,xcodebuildmcp@latest,mcp"

更多安装选项请参阅 入门指南。

系统要求

• macOS 14.5 或更高版本
• Xcode 16.x 或更高版本
• Node.js 18.x 或更高版本（通过 Homebrew 安装则无需此要求）

技能

XcodeBuildMCP 现在包含两种可选的代理技能：

• MCP 技能：为代理预置使用 MCP 服务器工具的指令（在使用 MCP 服务器时为可选项）。

• CLI 技能：为代理预置 CLI 导航指令（建议在使用 CLI 时启用）。

通过全局二进制安装：

xcodebuildmcp init

或者无需全局安装，直接通过 npx 安装：

npx -y xcodebuildmcp@latest init

有关安装技能的更多信息，请参阅：docs/SKILLS.md

注意事项

• XcodeBuildMCP 会请求 xcodebuild 跳过宏验证，以避免在构建使用 Swift Macros 的项目时出现错误。
• 设备工具需要在 Xcode 中配置代码签名。请参阅 docs/DEVICE_CODE_SIGNING.md。

隐私政策

XcodeBuildMCP 仅将 Sentry 用于内部运行时错误遥测。有关详细信息及退出说明，请参阅 docs/PRIVACY.md。

CLI

XcodeBuildMCP 提供统一的命令行界面。mcp 子命令用于启动 MCP 服务器，而其他所有命令则提供对工具的直接终端访问：

# 全局安装
npm install -g xcodebuildmcp@latest

# 启动 MCP 服务器（供 MCP 客户端使用）
xcodebuildmcp mcp

# 列出可用工具
xcodebuildmcp tools

# 为模拟器构建
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

CLI 使用基于工作区的守护进程来执行有状态的操作（日志捕获、调试等），该守护进程会在需要时自动启动。完整文档请参阅 docs/CLI.md。

文档

• 入门指南：docs/GETTING_STARTED.md
• CLI 使用：docs/CLI.md
• 配置与选项：docs/CONFIGURATION.md
• 工具参考：docs/TOOLS.md
• 故障排除：docs/TROUBLESHOOTING.md
• 隐私政策：docs/PRIVACY.md
• 技能：docs/SKILLS.md
• 贡献指南：docs/dev/CONTRIBUTING.md

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。 第三方许可声明请参阅 THIRD_PARTY_LICENSES 文件。 npm 包的归属信息请参阅 THIRD_PARTY_PACKAGE_LICENSES 文件。

XcodeBuildMCP 快速上手指南

XcodeBuildMCP 是一个基于模型上下文协议（MCP）的服务器和命令行工具，专为 iOS 和 macOS 项目开发设计，旨在辅助 AI 编程助手（Agent）更高效地构建、测试和管理苹果生态项目。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS 14.5 或更高版本
• 开发工具：Xcode 16.x 或更高版本
• 运行时依赖：Node.js 18.x 或更高版本（若使用 Homebrew 安装则无需单独安装 Node.js）

安装步骤

您可以选择通过 Homebrew 或 npm 进行安装。两种方式均包含 CLI 命令行工具和 MCP 服务器模式。

方式一：使用 Homebrew（推荐）

适合希望统一管理工具链的开发者。

# 添加仓库源
brew tap getsentry/xcodebuildmcp

# 安装工具
brew install xcodebuildmcp

验证安装：

xcodebuildmcp --help

方式二：使用 npm / npx

适合习惯 Node.js 生态或需要特定版本控制的开发者。

全局安装（用于直接使用 CLI）：

npm install -g xcodebuildmcp@latest
xcodebuildmcp --help

提示：如果您仅需在 AI 编辑器中作为 MCP 服务器使用，无需全局安装，可直接在配置中使用 npx 调用（见下文配置部分）。

基本使用

XcodeBuildMCP 提供两种主要使用场景：直接在终端运行命令，或集成到 AI 编程助手（如 Cursor, Claude Code, VS Code 等）中。

1. 终端命令行使用 (CLI)

安装完成后，您可以直接在终端执行构建、列出工具等操作。

查看可用工具列表：

xcodebuildmcp tools

为模拟器构建项目：

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

初始化 Agent 技能（可选）： 若需让 AI 更好地理解如何使用该工具，可运行初始化命令注入上下文技能：

xcodebuildmcp init
# 或者不全局安装直接运行
npx -y xcodebuildmcp@latest init

2. 集成到 AI 编程助手 (MCP Server)

将以下配置添加到您使用的 AI 客户端配置文件中，即可让 AI 自动调用 XcodeBuildMCP 的能力。

Cursor 编辑器

在项目根目录创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

(注：若使用 Homebrew 安装，请将 command 改为 "xcodebuildmcp"，args 改为 ["mcp"])

Claude Code

在终端运行以下命令自动添加：

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

VS Code

在设置 JSON (settings.json) 中添加：

"mcp": {
  "servers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

其他客户端 (Claude Desktop, Windsurf, Trae 等)

大多数客户端支持类似的 JSON 配置结构，核心配置如下：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
    }
  }
}

注意：

1. 真机调试工具需要先在 Xcode 中配置好代码签名。
2. 该工具会自动跳过 Swift Macros 的宏验证以避免构建错误。