XcodeBuildMCP

模型上下文协议 (MCP) 服务器，提供与 Xcode 相关的工具，用于与 AI 助手和其他 MCP 客户端集成。

概述

该项目实现了一个 MCP 服务器，它将 Xcode 操作公开为 AI 代理可以通过 MCP 协议调用的工具。它通过一个标准化接口实现了与 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 Extraction ：从 iOS 和 macOS 应用程序包中提取包标识符
应用程序启动：在模拟器和 macOS 上启动构建的应用程序

入门

先决条件

macOS 14.5 或更高版本
Xcode 16.x 或更高版本
米塞

使用 mise 进行单行设置

安装 mise：

# macOS (Homebrew)
brew install mise

# Other installation methods
# See https://mise.jdx.dev/getting-started.html

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

配置 MCP 客户端

配置您的 MCP 客户端（Windsurf、Cursor、Claude Desktop 等）以使用 XcodeBuildMCP 服务器，方法是修改客户端应用程序的 MCP 配置，更改版本号以匹配您希望使用的版本：

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

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

重要提示：XcodeBuildMCP 将请求 xcodebuild 跳过宏验证。这是为了避免在构建使用 Swift 宏的项目时出现错误。

在 VS Code 中单击即可安装

启用 UI 自动化（测试版）

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

brew tap facebook/fb
brew install idb-companion

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

pipx install fb-idb==1.1.7

重要提示：请注意，UI 自动化功能目前处于 Beta 阶段，因此可能存在一些不完善之处。如果您遇到任何问题，请在问题跟踪器中报告。

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

增量构建支持

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

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

MCP 客户端配置示例：

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

重要提示：请注意，增量构建支持目前处于高度实验阶段，您的实际体验可能会有所不同。请将您遇到的任何问题报告给问题跟踪器。

故障排除

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

诊断工具

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

与 mise 一起使用

# Run the diagnostic tool using mise
mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic

与 npx 一起使用

# Run the diagnostic tool using npx
npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

诊断工具将输出有关以下内容的综合信息：

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

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

MCP 服务器日志

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

光标：

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

如果您的 MCP 客户端没有日志文件，您可以使用 MCP 检查器工具直接运行服务器，有关如何操作的更多信息，请参阅“调试” 。运行 MCP 工具后，它会将所有日志消息打印到错误窗格中，这有助于诊断问题。

隐私

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

向 Sentry 发送了什么？

默认情况下，只有错误级别的日志和诊断信息才会发送到 Sentry。
错误日志可能包含错误消息、堆栈跟踪以及（在某些情况下）文件路径或项目名称等详细信息。您可以查看此存储库中的源代码，以准确了解记录的内容。

退出 Sentry

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

MCP 客户端配置示例：

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

选择性工具注册

默认情况下，所有工具均已启用，但对于某些客户端，仅启用特定工具可能会减少发送到客户端的上下文信息量。这可以通过在客户端 MCP 配置中设置特定的环境变量来实现。

一旦启用了一个或多个工具或工具组，所有其他工具都将被禁用。例如，如果只想启用与模拟器相关的工具，可以将环境变量设置为XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true这样将只显示用于在模拟器上构建、运行和调试的工具。

{
  "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 的方法。

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

Integrations

目录

概述