Xcode Build MCP Small

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


目录

• 概述
• 为什么？
• 特性

- Xcode项目管理 - Swift包管理器 - 模拟器管理 - 设备管理 - 应用程序实用程序 - MCP资源

• 入门

- 先决条件 - 配置您的MCP客户端 - 一键安装 - 一般安装 - 特定客户端安装说明 - OpenAI Codex命令行界面 - 克劳德代码CLI - 史密瑟里 - MCP兼容性

• 增量构建支持
• 动态工具

- 什么是动态工具？ - 如何启用动态工具 - 用法示例 - 客户端兼容性 - 选择性工作流加载（静态模式）

• 设备部署的代码签名
• 故障排除

- 医生工具

• 隐私

- 发送给Sentry的是什么？ - 选择退出哨兵

• 演示

- 自动修复Cursor中的构建错误 - 利用新的UI自动化和屏幕截图功能 - 在Claude Desktop中构建和运行iOS应用程序

• 贡献
• 许可证

概述

XcodeBuildMCP是一个模型上下文协议（MCP）服务器，它将Xcode操作作为AI助手和其他MCP客户端的工具和资源公开。它采用现代插件架构构建，提供了一套全面的自包含工具，这些工具组织在基于工作流的目录中，加上用于高效数据访问的MCP资源，通过标准化的接口实现与Xcode项目、模拟器、设备和Swift包的程序化交互。

Using Cursor to build, install, and launch an app on the iOS simulator while capturing logs at run-time.

为什么？

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

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

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

特性

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

Xcode项目管理

• 发现项目：Xcode项目和工作区发现
• 构建操作：适用于macOS、iOS模拟器和iOS设备目标的平台特定构建工具
• 项目信息：列出方案并显示Xcode项目和工作区的构建设置的工具
• 清洁操作：使用xcodebuild的本地清理操作清理构建产品
• 增量构建支持：使用增量构建支持的闪电快速构建（实验性，需要选择加入）
• 项目脚手架：使用工作区+SPM包架构、可定制的捆绑标识符、部署目标和设备系列，从现代模板创建新的iOS和macOS项目

Swift包管理器

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

模拟器管理

• 模拟器控制：列出、启动和打开模拟器
• 应用程序生命周期：完整的应用程序管理-在模拟器上安装、启动和停止应用程序
• 日志捕获：从模拟器中捕获运行时日志
• UI自动化：与模拟器UI元素交互
• 截图：从模拟器中截取屏幕截图
• 视频捕获：启动/停止模拟器视频捕获到MP4（AXe v1.1.0+）

设备管理

• 设备发现：列出通过USB或Wi-Fi连接的物理Apple设备
• 应用程序生命周期：完整的应用程序管理-在物理设备上构建、安装、启动和停止应用程序
• 测试：在具有详细结果和跨平台支持的物理设备上运行测试套件
• 日志捕获：从在物理Apple设备上运行的应用程序中捕获控制台输出
• 无线连接：支持通过Wi-Fi网络连接的设备

应用程序实用程序

• 捆绑ID提取：从所有Apple平台的应用程序包中提取包标识符
• 应用生命周期管理：在所有平台上完成应用程序生命周期控制

- 在模拟器、物理设备和macOS上启动应用程序 - 停止运行具有进程ID或捆绑包ID管理的应用程序 - 全面应用管理的过程监控

MCP资源

对于支持MCP资源的客户端，XcodeBuildMCP提供了高效的基于URI的数据访问：

• 模拟器资源 (xcodebuildmcp://simulators)：直接访问具有UUID和状态的可用iOS模拟器
• 设备资源 (xcodebuildmcp://devices)：通过UDID和状态直接访问连接的物理Apple设备
• 医生资源 (xcodebuildmcp://doctor)：直接访问Xcode版本、macOS版本和Node.js版本等环境信息

入门

先决条件

• macOS 14.5或更高版本
• Xcode 16.x或更高版本
• 节点18.x或更高版本

视频捕获需要捆绑的AXe二进制文件（v1.1.0+）。跑 npm run bundle:axe 使用前先在本地进行一次 record_sim_video。这不是单元测试所必需的。

配置您的MCP客户端

一键安装

要快速安装，您可以使用以下链接：


一般安装

大多数MCP客户端（Cursor、VS Code、Windsurf、Claude Desktop等）都已标准化以下JSON配置格式，只需将以下内容添加到客户端的JSON配置中即可 mcpServers 对象：

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

特定客户端安装说明

OpenAI Codex命令行界面

Codex使用toml配置文件来配置MCP服务器。使用配置XcodeBuildMCP OpenAI的Codex命令行界面，将以下配置添加到Codex CLI配置文件中：

[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest"]
env = { "INCREMENTAL_BUILDS_ENABLED" = "false", "XCODEBUILDMCP_SENTRY_DISABLED" = "false" }

有关更多信息，请参阅 OpenAI Codex MCP服务器配置 文档。

克劳德代码CLI

将XcodeBuildMCP与 克劳德代码，您可以通过命令行添加它：

# Add XcodeBuildMCP server to Claude Code
claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest

# Or with environment variables
claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest -e INCREMENTAL_BUILDS_ENABLED=false -e XCODEBUILDMCP_SENTRY_DISABLED=false

史密瑟里

通过以下方式自动安装适用于Claude Desktop的XcodeBuildMCP服务器 史密瑟里:

npx -y @smithery/cli install @cameroncooke/XcodeBuildMCP --client claude

\[！重要\] 请注意，XcodeBuildMCP将请求xcodebuild跳过宏验证。这是为了避免在构建使用Swift宏的项目时出错。

MCP兼容性

XcodeBuildMCP支持MCP工具、资源和采样。在撰写本文时，以下编辑器具有不同级别的MCP功能支持：

增量构建支持

XcodeBuildMCP包括对增量构建的实验支持。默认情况下，此功能处于禁用状态，可以通过设置 INCREMENTAL_BUILDS_ENABLED 环境变量 true:

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

MCP配置示例：

"XcodeBuildMCP": {
  ...
  "env": {
    "INCREMENTAL_BUILDS_ENABLED": "true"
  }
}

\[！重要\] 请注意，增量构建支持目前处于高度试验阶段，您的里程可能会有所不同。请将您遇到的任何问题报告给 问题跟踪系统.

动态工具

XcodeBuildMCP支持动态工具加载，以优化AI助手中的上下文窗口使用。此功能对于管理XcodeBuildMCP提供的广泛工具集特别有用。

什么是动态工具？

默认情况下，XcodeBuildMCP在启动时加载所有可用工具（静态模式），这提供了对完整工具集的即时访问，但使用了更大的上下文窗口。动态工具模式通过以下方式解决了这个问题：

1. 开始最小：只有基本工具，如 discover_tools 和 discover_projs 最初可用
2. 人工智能驱动的发现：当AI代理识别出XcodeBuildMCP可以帮助完成开发任务时，它会自动使用 discover_tools 工具
3. 智能装载：服务器使用LLM调用来识别最相关的工作流组，并仅动态加载这些工具
4. 上下文效率：将整个工具列表中的初始上下文足迹减少到只有2个发现工具，同时保持完整的功能

如何启用动态工具

要启用动态工具，请设置 XCODEBUILDMCP_DYNAMIC_TOOLS 环境变量 true:

MCP客户端配置示例：

"XcodeBuildMCP": {
  ...
  "env": {
    "XCODEBUILDMCP_DYNAMIC_TOOLS": "true"
  }
}

用法示例

一旦启用，AI代理就会根据上下文自动发现和加载相关工具。例如，当您提到使用iOS应用程序或代理在您的工作区中检测到iOS开发任务时，它将自动使用 discover_tools 该工具用于加载工作流所需的适当模拟器和项目工具。

客户端兼容性

动态工具需要支持以下功能的MCP客户端 MCP采样 为了使AI驱动的工具发现发挥作用：

\[！注意\] 对于不支持MCP采样的客户端，XcodeBuildMCP将自动回退到静态模式，在启动时加载所有工具，而不管 XCODEBUILDMCP_DYNAMIC_TOOLS 设置。

选择性工作流加载（静态模式）

对于不支持MCP采样但仍希望减少上下文窗口使用的客户端，您可以使用 XCODEBUILDMCP_ENABLED_WORKFLOWS 环境变量：

"XcodeBuildMCP": {
  ...
  "env": {
    "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery"
  }
}

可用工作流：

• device （14个工具）-iOS设备开发
• simulator （18个工具）-iOS模拟器开发
• simulator-management （8个工具）-模拟器管理
• swift-package （6个工具）-Swift包管理器
• project-discovery （5个工具）-项目发现
• macos （11个工具）-macOS开发
• ui-testing （11个工具）-UI测试和自动化
• logging （4个工具）-日志捕获和管理
• project-scaffolding （2个工具）-项目脚手架
• utilities （1个工具）-项目实用程序
• doctor （1个工具）-系统医生
• discovery （1个工具）-动态工具发现

\[！注意\] 这 XCODEBUILDMCP_ENABLED_WORKFLOWS 该设置仅在静态模式下有效。如果 XCODEBUILDMCP_DYNAMIC_TOOLS=true 如果已设置，则将忽略选择性工作流设置。

设备部署的代码签名

为了使设备部署功能正常工作，必须在Xcode中正确配置代码签名 之前 使用XcodeBuildMCP设备工具：

1. 在Xcode中打开您的项目
2. 选择您的项目目标
3. 转到“签名和功能”选项卡
4. 配置“自动管理签名”并选择您的开发团队
5. 确保选择了有效的配置文件

备注：XcodeBuildMCP无法自动配置代码签名。此初始设置必须在Xcode中完成一次，之后MCP设备工具可以在物理设备上构建、安装和测试应用程序。

故障排除

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

医生工具

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

# Run the doctor tool using npx
npx --package xcodebuildmcp@latest xcodebuildmcp-doctor

医生工具将输出以下综合信息：

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

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

隐私

此项目使用 哨兵 用于错误监测和诊断。Sentry帮助我们跟踪问题、崩溃和意外错误，以提高XcodeBuildMCP的可靠性和稳定性。

发送给Sentry的是什么？

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

选择退出哨兵

• 如果您不希望向Sentry发送错误日志，可以通过设置环境变量来选择退出 XCODEBUILDMCP_SENTRY_DISABLED=true.

MCP客户端配置示例：

"XcodeBuildMCP": {
  ...
  "env": {
    "XCODEBUILDMCP_SENTRY_DISABLED": "true"
  }
}

演示

自动修复Cursor中的构建错误

利用新的UI自动化和屏幕截图功能

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

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

贡献

 ](https://nodejs.org/)

欢迎投稿！以下是如何帮助改进XcodeBuildMCP。

请参阅我们的开发文档：

• 贡献 -贡献指南和开发设置
• 代码质量 -代码质量标准、linting和架构规则
• 测试 -测试原理和模式
• 建筑 -系统架构和设计原则

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。