---
title: "Xcode 集成"
description: "基于 Cursor 官方 Xcode integration 文档解释 Xcode 26.3+ MCP bridge、xcrun mcpbridge、20 个 tools、CLI 和排障。"
verifiedAt: "2026-05-09"
---

Xcode 26.3+ 提供内置 MCP server，Cursor 可以通过它直接访问 Xcode projects。

> [!NOTE]
> **阅读目标**：读完本章，你应该能把 Xcode 的 MCP bridge 接入 Cursor，并知道 agent 能做哪些 iOS/macOS 开发动作、哪些错误该怎么排。

## 1. 工作方式

Apple 在 Xcode 中提供 `xcrun mcpbridge`。它把 MCP protocol messages 转换到 Xcode 的内部 XPC layer，让 Cursor 像使用其他 MCP server 一样调用 Xcode tools。

```mermaid
flowchart LR
  Cursor["Cursor / Cursor CLI"] --> MCP["MCP stdio server"]
  MCP --> Bridge["xcrun mcpbridge"]
  Bridge --> Xcode["Running Xcode project"]
  Xcode --> Build["Build / tests / previews / docs"]
```

前提是 Xcode 正在运行并打开了项目。空窗口或没打开 workspace 时，很多工具没有上下文。

## 2. 前置条件

| 条件 | 要求 |
| --- | --- |
| macOS | 安装 Xcode 26.3 或更高 |
| Cursor | paid Cursor plan |
| Xcode project | 项目必须在 Xcode 中打开，Xcode 必须运行 |
| MCP bridge | Xcode Settings -> Intelligence 中开启 Xcode Tools |

如果 Xcode 设置里没有 MCP 选项，先检查版本。官方当前要求 Xcode 26.3+。

## 3. 开启 Xcode MCP

在 Xcode 中：

1. 打开 Xcode -> Settings -> Intelligence。
2. 在 Model Context Protocol 下启用 Xcode Tools。

在 Cursor 中有三种配置方式：

| 方式 | 操作 |
| --- | --- |
| MCP settings UI | Cursor Settings -> Features -> MCP -> Add New MCP Server |
| `mcp.json` | 添加 `xcode-tools`，command 用 `xcrun`，args 用 `mcpbridge` |
| Cursor CLI | 运行 `agent mcp add xcode-tools -- xcrun mcpbridge` |

CLI 和 editor 共享 MCP config，所以用 CLI 添加后，editor 里也能看到。

## 4. 20 个内置 tools

Xcode 暴露 20 个 MCP tools，分五类。

| 类别 | Tools |
| --- | --- |
| File operations | `XcodeRead`、`XcodeWrite`、`XcodeUpdate`、`XcodeGrep`、`XcodeGlob`、`XcodeLS`、`XcodeMakeDir`、`XcodeRM`、`XcodeMV` |
| Build and test | `BuildProject`、`GetBuildLog`、`RunAllTests`、`RunSomeTests`、`GetTestList` |
| Diagnostics | `XcodeListNavigatorIssues`、`XcodeRefreshCodeIssuesInFile` |
| Intelligence | `RenderPreview`、`DocumentationSearch`、`ExecuteSnippet` |
| Workspace | `XcodeListWindows` |

其中 `XcodeRead` 单次最多读取 600 行，较大文件要用 offset / limit 分段。

## 5. 典型工作流

一次稳定的 Cursor + Xcode 工作流：

1. 同时在 Cursor 和 Xcode 中打开项目。
2. 让 agent 添加功能或修 bug。
3. agent 用 `XcodeRead` / `XcodeGrep` 理解代码。
4. agent 用 `XcodeWrite` / `XcodeUpdate` 修改文件。
5. agent 运行 `BuildProject`。
6. agent 用 `GetBuildLog` 查看错误。
7. agent 用 `RunSomeTests` 验证目标测试。
8. UI 改动时，用 `RenderPreview` 抓 SwiftUI preview。

Xcode 负责编译、测试和预览，Cursor 负责 agent 推理、编辑和任务编排。

## 6. Cursor CLI with Xcode

Cursor CLI 也可以使用同一个 `xcode-tools` MCP server。

适合：

- terminal-first 开发者。
- headless workflows。
- CI 前的本地自动验证。
- 让 agent 针对某个类或测试运行一次小任务。

注意：Xcode MCP 仍依赖正在运行的 Xcode session。完全无 GUI 的 CI 不一定满足这个前提。

## 7. 常见排障

| 问题 | 处理 |
| --- | --- |
| Cursor 找不到 `xcode-tools` | 确认 Xcode 正在运行并打开项目 |
| missing `tabIdentifier` | 确认打开的是 project / workspace，不是空窗口 |
| build / test timeout | 到 Xcode 看底层构建是否仍在运行，大项目可能只是耗时 |
| Xcode settings 没有 MCP toggle | 检查 Xcode 版本是否为 26.3+ |
| `xcrun` 找不到 `mcpbridge` | 用 `xcode-select` 指向完整 Xcode，而不是 Command Line Tools |

如果系统指向 Command Line Tools，需要切到完整 Xcode Developer 目录，再运行 first launch，并确认 `xcrun --find mcpbridge` 返回路径。

## 8. 商业级验收

上线前至少确认：

- Xcode 版本和 MCP toggle 可见。
- Cursor MCP settings 中 `xcode-tools` 连接正常。
- agent 能读取当前项目文件。
- agent 能运行一次 build 并读取 build log。
- agent 能运行目标测试或列出测试。
- SwiftUI 项目能抓 preview。
- 大项目 timeout 和日志路径写进 SOP。
- 破坏性工具如 `XcodeRM`、`XcodeMV` 的使用边界明确。

## 官方来源

- [Cursor Xcode Integration](https://cursor.com/docs/integrations/xcode.md) —— 官方 Xcode MCP bridge、setup、tools、workflow、CLI 和 troubleshooting。
- [Cursor MCP](https://cursor.com/docs/mcp.md) —— MCP 配置背景。
- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— CLI 与 MCP server 共享配置背景。

## 接下来去哪

<Cards>
  <Card title="TypeScript SDK" description="继续学习用 SDK 把 Cursor 能力接入自己的工具。" href="/docs/cursor/official/05-integrations-sdk/76-typescript-sdk" />
  <Card title="MCP" description="回看 MCP server 配置和权限边界。" href="/docs/cursor/official/02-context-customization/21-mcp" />
</Cards>
