Xcode: MCP Bridge Wrapper for Cursor

Xcode MCP Bridge 封装器

mcpbridge-wrapper 通过 Apple 的 xcrun mcpbridge 将外部 MCP 客户端连接到 Xcode。它会修复声明了 outputSchema 却未提供 structuredContent 的 Xcode 工具响应。该修复在直接模式和 代理模式下均有效。代理模式还支持多个客户端共享一个持久的 Xcode 连接，从而减少重复的连接提示。

兼容性

组件	0.5.0 支持情况
Xcode	macOS 上的 26.3+ 和 27.0；已验证 Xcode 27.0 握手和工具发现
MCP 客户端	使用 initialize 生命周期的客户端；请确认客户端版本使用的协议
MCP 2026-07-28	0.5.0 不支持；无会话实现仍在单独分支上进行实验
Python	3.9-3.12；uvx 会管理自身环境

该封装器不会捆绑 Xcode 工具。它会公开已安装 Xcode 返回的工具目录，因此工具名称和可用性可能会随 Xcode 更新和权限设置而变化。使用构建版本 27A266a 时观察到的 Xcode 27.0 工具目录列在下方。

快速入门

1. 安装 uv 和 Xcode 26.3 或更高版本。支持 Xcode 27.0。
2. 在 Xcode > Settings > Intelligence > Model Context Protocol 中，启用 Allow external agents to use Xcode tools。在 Xcode 中打开要使用的项目。请参阅 Apple 的设置指南。
3. 添加下方的一种客户端配置。固定为 0.5.0，以便在未来发布主版本后继续使用旧版 MCP 契约。
4. 启动客户端；如果出现 Xcode 访问提示，请批准。批准后，在客户端中重新加载或重新连接 MCP 服务，以便再次获取 tools/list，然后通过实际调用 Xcode 工具进行验证。MCP 指示灯变绿本身只能确认握手成功。

多个客户端建议使用代理模式。所有示例都使用同一个按用户运行的守护进程。第一个客户端会启动它；后续客户端会复用它。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper==0.5.0", "mcpbridge-wrapper", "--broker"]
    }
  }
}

Codex

添加到 ~/.codex/config.toml 并重启 Codex：

[mcp_servers.xcode-tools]
command = "uvx"
args = ["--from", "mcpbridge-wrapper==0.5.0", "mcpbridge-wrapper", "--broker"]

Zed

在顶层 context_servers 键下，添加到 ~/.config/zed/settings.json，然后在 Settings > AI > MCP Servers 中停用并重新启用该服务：

{
  "context_servers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper==0.5.0", "mcpbridge-wrapper", "--broker"],
      "env": {}
    }
  }
}

有关设置界面和服务状态指示灯，请参阅 Zed 的 MCP 配置指南。

Claude Code

claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper==0.5.0' mcpbridge-wrapper --broker

如果只有一个客户端且不需要共享守护进程，请从其命令中移除 --broker 以使用直接模式。手动安装和 Web UI 选项详见安装、 代理模式和 Web UI 指南。

Xcode 27.0 审批与验证

Xcode 27.0 可能会请求授予代理主机进程和项目文件夹的权限。提示中会显示 Python 可执行文件和 PID，而不是编辑器名称。即使之前已允许旧版 Python 安装，也可能需要重新审批新的 uvx 主机身份。只有在路径和项目都符合预期时，才批准访问。

如果工具报告 Agent 尚未获批，请使用 XcodeOpenWorkspace 并提供现有 .xcodeproj 或 .xcworkspace 的绝对路径来请求访问权限，在 Xcode 中批准提示，然后重试只读工具。不要将 tools/list 成功执行或客户端状态指示灯变绿视为 Xcode 工具调用已获授权的证据。使用以下命令检查 Xcode 的状态：

xcrun mcp-server status
uvx --from 'mcpbridge-wrapper==0.5.0' mcpbridge-wrapper --broker-status

第二条命令应显示 Proxy version: 0.5.0 和 Daemon version: 0.5.0。如果仍在运行旧版守护进程，请将其停止一次，然后重新连接客户端：

uvx --from 'mcpbridge-wrapper==0.5.0' mcpbridge-wrapper --broker-stop

停止单例会暂时断开所有正在使用它的客户端。下次使用 --broker 连接时会启动新的守护进程。如需稳定且长期运行的主机身份，请参阅专用代理主机。

Xcode 27.0 工具

在本地冒烟测试期间，Xcode 27.0 构建版本 27A266a 的 tools/list 显示了 54 个工具。这是观测到的目录，并非硬编码的包装器 API。Xcode 27 新增了工作区创建与打开、模拟器交互、运行和调试器控制、构建配置、本地化以及崩溃与线上洞察工具。请参阅 Apple 的 Xcode 27 发行说明。

• 工作区与目标： XcodeListWorkspaces、XcodeOpenWorkspace、 XcodeCloseWorkspace、XcodeNewProject、XcodeNewTarget、 XcodeListTargets、XcodeListTemplates、XcodeListSchemes、 XcodeSwitchScheme、XcodeListRunDestinations、 XcodeSwitchRunDestination、XcodeListTestPlans、XcodeSwitchTestPlan。
• 文件与诊断： XcodeRead、XcodeWrite、XcodeUpdate、 XcodeLS、XcodeGlob、XcodeGrep、XcodeMakeDir、XcodeMV、XcodeRM、 XcodeRefreshCodeIssuesInFile。
• 构建、测试、运行与调试： BuildProject、GetBuildLog、 GetTestList、RunAllTests、RunSomeTests、RunProject、StopProject、 GetConsoleOutput、InvokeDebuggerCommand、GetFileCompilerFlags、 UpdateFileCompilerFlags、GetTargetBuildSettings、 UpdateTargetBuildSetting。
• 设备交互： DeviceInteractionStartSession、 DeviceInteractionStartWorkspaceSession、DeviceInteractionInstallAndRun、 DeviceInteractionSynthesize、DeviceInteractionEndSession。
• 本地化： LocalizationPlanner、StringCatalogContext、 StringCatalogRead、StringCatalogEdit。
• 崩溃与线上洞察： GetTopCrashIssues、GetCrashIssueLogs、 GetTopFieldPerformanceIssues、GetFieldPerformanceIssueLogs。
• 预览与参考： RenderPreview、DocumentationSearch、 RunCodeSnippet。
• 项目元数据： AddEntitlement、AddInfoPlist。

在此目录中，旧名称 XcodeListWindows 已不存在；请在 Xcode 批准后使用 XcodeListWorkspaces 检查工作区。构建、文件编辑和设备交互等工具调用可能会更改项目或设备状态。验证新配置时，请先使用只读调用。

开发

有关源码安装和质量门禁，请参阅贡献指南。此软件包也可从 PyPI 获取，并可在 MCP Registry 中找到。

基于 MIT 许可证授权。