XcodeBuildMCP

开发 TypeScript

🚀 XcodeBuildMCP：集成AI助手与Xcode的MCP服务器

XcodeBuildMCP是一个模型上下文协议（MCP）服务器，它提供与Xcode相关的工具，可集成AI助手和其他MCP客户端，助力开发者更高效地进行Xcode项目开发。

🚀 快速开始

项目概述

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

使用Cursor在iOS模拟器上构建、安装和启动应用程序，并在运行时捕获日志。

项目存在的意义

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

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

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

前提条件

macOS 14.5 或更高版本
Xcode 16.x 或更高版本
Node 18.x 或更高版本
AXe 1.0.0 或更高版本（可选，UI自动化需要）

UI自动化

若要使用UI自动化功能（点击、滑动、输入等），你需要安装AXe：

brew tap cameroncooke/axe
brew install axe

有关AXe和其他安装方法的更多信息，请参阅 AXe仓库。

配置MCP客户端

快速安装

你可以使用以下链接进行快速安装：

手动安装

通过修改客户端应用程序的MCP配置，将你的MCP客户端（Windsurf、Cursor、Claude Desktop、Claude Code等）配置为使用XcodeBuildMCP服务器。

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

使用mise的替代安装方法

你也可以使用mise来安装XcodeBuildMCP，而无需单独安装Node.js：

# macOS (Homebrew)
brew install mise

# 其他安装方法
# 请参阅 https://mise.jdx.dev/getting-started.html

然后将你的MCP客户端配置为使用mise安装XcodeBuildMCP：

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

⚠️ 重要提示 使用mise时，避免使用@latest标签，因为mise会缓存软件包，可能不会自动更新到最新版本，建议使用明确的版本号。

⚠️ 重要提示 请注意，XcodeBuildMCP会请求xcodebuild跳过宏验证，这是为了避免在构建使用Swift宏的项目时出错。

✨ 主要特性

Xcode项目管理

项目发现：发现Xcode项目和工作区
构建操作：针对macOS、iOS模拟器和iOS设备目标的特定平台构建工具
项目信息：列出Xcode项目和工作区的方案并显示构建设置的工具
清理操作：使用xcodebuild的原生清理操作清理构建产品
增量构建支持：使用增量构建支持实现闪电般快速的构建（实验性，需要手动启用）
项目搭建：使用现代模板创建新的iOS和macOS项目，具备工作区 + SPM包架构，可自定义捆绑标识符、部署目标和设备系列

Swift包管理器

包构建：使用配置和架构选项构建Swift包
测试运行：执行Swift包测试套件，支持过滤和并行执行
可执行文件运行：执行包二进制文件，支持超时处理和后台执行
进程管理：列出并停止使用Swift包工具启动的长时间运行的可执行文件
工件清理：删除构建工件和派生数据以进行全新构建

模拟器管理

模拟器控制：列出、启动和打开iOS模拟器
应用部署：在iOS模拟器上安装和启动应用程序
日志捕获：从模拟器捕获运行时日志
UI自动化：与模拟器UI元素进行交互（测试版）
屏幕截图：从模拟器捕获屏幕截图（测试版）

应用实用工具

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

📦 安装指南

增量构建支持

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

启用增量构建的示例MCP客户端配置：

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

⚠️ 重要提示 请注意，增量构建支持目前处于高度实验阶段，实际效果可能会有所不同。如果你遇到任何问题，请向问题跟踪器报告。

🔧 技术细节

故障排除

诊断工具

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

使用npx

# 使用npx运行诊断工具
npx xcodebuildmcp@1.7.0 xcodebuildmcp-diagnostic

使用mise

# 使用mise运行诊断工具
mise x npm:xcodebuildmcp@1.7.0 -- xcodebuildmcp-diagnostic

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

系统和Node.js环境
Xcode安装和配置
所需的依赖项（xcodebuild、AXe等）
影响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来退出。

退出Sentry的示例MCP客户端配置：

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

选择性工具注册

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

启用一个或多个工具或工具组后，所有其他工具将被禁用。例如，若要仅启用与模拟器相关的工具，可以将环境变量设置为XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true，这样将仅暴露用于在模拟器上构建、运行和调试的工具。

{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": [
"-y",
"xcodebuildmcp@latest"
],
"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 文档。