一个提供与AI助手及其他MCP客户端集成的Xcode相关工具的模型上下文协议（MCP）服务器。

目录

• 概述
• 为什么？
• 功能
  • Xcode项目管理
  • 模拟器管理
  • 应用程序实用工具
• 开始使用
  • 先决条件
  • 使用mise进行单行设置
  • 配置MCP客户端
    • 在VS Code中一键安装
  • 启用UI自动化（测试版）
• 增量构建支持
• 故障排除
  • 诊断工具
    • 使用mise
    • 使用npx
  • MCP服务器日志
• 隐私
  • 发送到Sentry的内容是什么？
  • 选择退出Sentry
• 选择性工具注册
• 演示
  • 在Cursor中自动修复构建错误
  • 利用新的UI自动化和屏幕捕获功能
  • 在Claude Desktop中构建和运行iOS应用
• 贡献
• 许可证

概述

该项目实现了一个MCP服务器，通过MCP协议将Xcode操作作为工具暴露出来，供AI代理调用。它通过标准化接口实现了与Xcode项目的程序化交互，优化了以代理驱动的开发工作流程。

为什么？

XcodeBuild MCP工具主要目的是简化和标准化AI代理与Xcode项目之间的交互。通过为常见的Xcode操作提供专用工具，它消除了对手动或可能不正确的命令行调用的依赖。

这确保了一个可靠且高效的开发过程，使代理能够无缝地利用Xcode的功能，同时减少了配置错误的风险。

关键的是，这个MCP使AI代理能够独立验证代码更改，通过构建项目、检查错误并自主迭代。与用户驱动的工具如Sweetpad相比，XcodeBuild MCP使代理能够有效地自动化这些工作流程。

功能

XcodeBuildMCP服务器提供了以下工具功能：

Xcode项目管理

• 发现项目：发现Xcode项目和工作区
• 构建操作：针对macOS、iOS模拟器和iOS设备目标的平台特定构建工具
• 项目信息：列出方案和显示Xcode项目及工作区的构建设置的工具
• 清理操作：使用xcodebuild的原生清理操作清理构建产物
• 增量构建支持：使用增量构建支持实现闪电般的快速构建（实验性，需要选择加入）### 模拟器管理
• 模拟器控制: 列出、启动和打开 iOS 模拟器
• 应用程序部署: 在 iOS 模拟器上安装和启动应用程序
• 日志捕获: 从模拟器中捕获运行时日志
• UI 自动化: 与模拟器 UI 元素交互（测试版）
• 屏幕截图: 从模拟器中捕获屏幕截图（测试版）

应用程序实用工具

• Bundle ID 提取: 从 iOS 和 macOS 应用程序包中提取 Bundle 标识符
• 应用程序启动: 在模拟器和 macOS 上启动已构建的应用程序

开始使用

前提条件

• macOS 14.5 或更高版本
• Xcode 16.x 或更高版本
• mise

使用 mise 一键设置

要安装 mise:
bash

macOS (Homebrew)

brew install mise

其他安装方法

查看 https://mise.jdx.dev/getting-started.html

有关 mise 的更多信息，请访问 官方文档。

配置 MCP 客户端

配置您的 MCP 客户端（如 Windsurf, Cursor, Claude Desktop 等）以使用 XcodeBuildMCP 服务器，通过修改客户端应用程序的 MCP 配置，并将版本号更改为所需的版本：

json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:xcodebuildmcp@1.4.0",
"--",
"xcodebuildmcp"
]
}
}
}

[!NOTE]
当使用 mise 时，请避免使用 @latest 标签，因为 mise 会缓存包并且可能不会自动更新到最新版本，建议使用明确的版本号。

[!IMPORTANT]
请注意，XcodeBuildMCP 将请求 xcodebuild 跳过宏验证。这是为了避免在构建使用 Swift Macros 的项目时出现错误。

在 VS Code 中一键安装

启用 UI 自动化（测试版）

对于 UI 自动化功能（点击、滑动、截图等），您需要安装 Facebook 的 idb_companion：

bash
brew tap facebook/fb
brew install idb-companion

还需要 idb 客户端，但 XcodeBuildMCP 会尝试为您安装它。如果发现 UI 自动化功能仍然不可用，您可以手动安装客户端，使用以下命令（假设您已安装 Python）：

bash
pipx install fb-idb==1.1.7

[!IMPORTANT]
请注意，UI 自动化功能目前处于测试阶段，可能会有一些不完善之处。如果您遇到任何问题，请在 问题跟踪器 中报告。

[!NOTE]
并非所有 MCP 客户端都支持在工具响应中显示图像以及将其嵌入聊天上下文中；目前已知 Cursor 支持此功能。

增量构建支持XcodeBuildMCP 包含了对增量构建的实验性支持。此功能默认是禁用的，可以通过将 INCREMENTAL_BUILDS_ENABLED 环境变量设置为 true 来启用：

要启用增量构建，请将 INCREMENTAL_BUILDS_ENABLED 环境变量设置为 true：

示例 MCP 客户端配置：
bash
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:xcodebuildmcp@1.4.0",
"--",
"xcodebuildmcp"
],
"env": {
"INCREMENTAL_BUILDS_ENABLED": "true"
}
}
}
}

[!IMPORTANT]
请注意，目前增量构建的支持还处于高度实验阶段，效果可能因人而异。如果您遇到任何问题，请向 问题跟踪器 报告。

故障排除

如果您在使用 XcodeBuildMCP 时遇到问题，诊断工具可以帮助通过提供关于您的环境和依赖项的详细信息来识别问题。

诊断工具

诊断工具是一个独立的实用程序，它检查您的系统配置并报告 XcodeBuildMCP 所需的所有依赖项的状态。在报告问题时特别有用。

使用 mise

bash

使用 mise 运行诊断工具

mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic

使用 npx

bash

使用 npx 运行诊断工具

npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

诊断工具将输出以下方面的综合信息：

• 系统和 Node.js 环境
• Xcode 的安装与配置
• 必需的依赖项（如 xcodebuild, idb 等）
• 影响 XcodeBuildMCP 的环境变量
• 功能可用状态

在 GitHub 上报告问题时，请包含诊断工具的完整输出以帮助进行故障排除。

MCP 服务器日志

访问来自 MCP 服务器的日志消息有助于识别任何问题。这些日志由客户端应用程序捕获，例如在 Cursor 中：

Cursor:
bash
find ~/Library/Application Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

如果您的 MCP 客户端没有日志文件，您可以直接使用 MCP Inspector 工具运行服务器，请参阅 调试 获取更多信息。一旦运行，MCP 工具会将其所有日志消息打印到错误面板中，这有助于诊断问题。

隐私

本项目使用 Sentry 进行错误监控和诊断。Sentry 帮助我们追踪问题、崩溃和意外错误，以提高 XcodeBuildMCP 的可靠性和稳定性。

发送到 Sentry 的内容是什么？

• 默认情况下，仅发送错误级别的日志和诊断信息到 Sentry。
• 错误日志可能包括诸如错误消息、堆栈跟踪以及（在某些情况下）文件路径或项目名称等细节。您可以通过查看此仓库中的源代码来了解具体记录了哪些内容。

选择不使用 Sentry

• 如果您不想将错误日志发送给 Sentry，可以通过设置环境变量 SENTRY_DISABLED=true 来选择退出。

示例 MCP 客户端配置：
bash
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:xcodebuildmcp@1.4.0",
"--",
"xcodebuildmcp"
],
"env": {
"SENTRY_DISABLED": "true"
}
}
}
}

选择性工具注册

默认情况下，所有工具都是启用的，但对于某些客户端来说，只启用特定工具以减少发送给客户端的上下文量可能是有用的。这可以通过在客户端的 MCP 配置中设置特定的环境变量来实现。一旦启用了一个或多个工具或工具组，所有其他工具将被禁用。例如，要仅启用与模拟器相关的工具，可以将环境变量设置为 XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true，这将只暴露用于在模拟器上构建、运行和调试的工具。

bash
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "mise",
"args": [
"x",
"npm:xcodebuildmcp@1.4.0",
"--",
"xcodebuildmcp"
],
"env": {
"XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
}
}
}
}

你可以在 TOOL_OPTIONS.md 文件中找到可用工具的列表以及如何启用它们的详细说明。

演示

在 Cursor 中自主修复构建错误

利用新的 UI 自动化和屏幕捕获功能

在 Claude Desktop 中构建和运行 iOS 应用

https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086

贡献

欢迎贡献！以下是如何帮助改进 XcodeBuildMCP 的方法。

请参阅我们的 CONTRIBUTING 文档以获取有关如何配置本地环境并为项目做出贡献的更多信息。

许可证

该项目根据 MIT 许可证授权 - 详情请参见 LICENSE 文件。

MCP 服务器验证

Glama.ai

MseeP.a