---
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="/zh-Hant/docs/cursor/official/05-integrations-sdk/76-typescript-sdk" />
  <Card title="MCP" description="回看 MCP server 配置和許可權邊界。" href="/zh-Hant/docs/cursor/official/02-context-customization/21-mcp" />
</Cards>
