axiom-xcode-mcp-setup

Xcode MCP 配置

前置条件

• 支持 MCP 的 Xcode 26.3+
• 已安装并运行 Xcode 的 macOS
• Xcode 中至少打开一个项目/工作区

第 1 步：在 Xcode 中启用 MCP

1. 打开 Xcode 设置（Cmd+,）
2. 转到 Intelligence 标签页
3. 勾选 Enable Model Context Protocol
4. 确保 Xcode Tools 开关处于开启状态

如果不开启此开关，xcrun mcpbridge 虽然可以连接，但不会返回任何工具。

第 2 步：连接 MCP 客户端

Claude Code

claude mcp add --transport stdio xcode -- xcrun mcpbridge

验证：claude mcp list 应显示 xcode 服务。

Codex

codex mcp add xcode -- xcrun mcpbridge

Cursor

在项目根目录中创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}

Cursor 特别说明：Cursor 是严格的 MCP 客户端。Xcode 的 mcpbridge 在工具声明了 outputSchema 时会省略 structuredContent，这违反了 MCP 规范。如果 Cursor 拒绝响应，请使用 XcodeMCPWrapper 作为代理：

{
  "mcpServers": {
    "xcode": {
      "command": "/path/to/XcodeMCPWrapper",
      "args": []
    }
  }
}

VS Code + GitHub Copilot

创建或编辑 .vscode/mcp.json：

{
  "servers": {
    "xcode": {
      "type": "stdio",
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}

Gemini CLI

gemini mcp add xcode -- xcrun mcpbridge

第 3 步：验证连接

配置完成后，调用 XcodeListWindows（无参数）。你应该会看到：

tabIdentifier: <uuid>, workspacePath: /path/to/YourProject.xcodeproj

如果列表为空，请确保 Xcode 中已打开项目。

权限对话框

MCP 客户端首次连接时，Xcode 会显示权限对话框：

• 通过 PID 识别连接进程
• 询问是否允许访问 MCP 工具
• 必须在 Xcode UI 中批准（而不是在终端中）

基于 PID 的批准：权限按进程授予。如果客户端重启（PID 更改），对话框会再次出现。这是预期行为。

多个 Xcode 实例的目标选择

当多个 Xcode 实例正在运行时：

自动检测（默认）

mcpbridge 按以下回退顺序自动选择：

1. 如果恰好有一个 Xcode 进程正在运行 → 使用该进程
2. 如果有多个 → 使用与 xcode-select 匹配的进程
3. 如果没有 → 退出并报错

手动选择 PID

将 MCP_XCODE_PID 设置为目标实例：

# Find Xcode PIDs
pgrep -x Xcode

# Claude Code with specific PID
claude mcp add --transport stdio xcode -- env MCP_XCODE_PID=12345 xcrun mcpbridge

会话 ID（可选）

MCP_XCODE_SESSION_ID 为工具会话提供稳定的 UUID，便于跟踪重新连接前后的交互。

故障排除

digraph troubleshoot {
    rankdir=TB;
    "Connection failed?" [shape=diamond];
    "tools/list empty?" [shape=diamond];
    "Wrong project?" [shape=diamond];
    "Repeated permission prompts?" [shape=diamond];
    "Client rejects responses?" [shape=diamond];

    "Check Xcode running + toggle on" [shape=box];
    "Open a project in Xcode" [shape=box];
    "Use MCP_XCODE_PID or check tab targeting" [shape=box];
    "Expected: PID changes on restart" [shape=box];
    "Use XcodeMCPWrapper proxy" [shape=box];

    "Connection failed?" -> "Check Xcode running + toggle on" [label="refused/timeout"];
    "Connection failed?" -> "tools/list empty?" [label="connects OK"];
    "tools/list empty?" -> "Open a project in Xcode" [label="no tools"];
    "tools/list empty?" -> "Wrong project?" [label="tools listed"];
    "Wrong project?" -> "Use MCP_XCODE_PID or check tab targeting" [label="yes"];
    "Wrong project?" -> "Repeated permission prompts?" [label="no"];
    "Repeated permission prompts?" -> "Expected: PID changes on restart" [label="yes"];
    "Repeated permission prompts?" -> "Client rejects responses?" [label="no"];
    "Client rejects responses?" -> "Use XcodeMCPWrapper proxy" [label="strict client (Cursor)"];
}

常见问题

现象	原因	解决方法
"Connection refused"	Xcode 未运行或 MCP 开关已关闭	启动 Xcode，在 Settings > Intelligence 中启用 MCP
tools/list 返回空结果	未打开项目，或未授予权限	打开项目，并检查 Xcode 中是否出现权限对话框
工具针对了错误的项目	存在多个 Xcode 窗口，或选错标签页	调用 XcodeListWindows，使用正确的 tabIdentifier
反复出现权限提示	客户端已重启（PID 更改）	这是预期行为 — 每次都需批准
Cursor/严格客户端报错	响应中缺少 structuredContent	使用 XcodeMCPWrapper 作为代理
"No such command: mcpbridge"	Xcode 低于 26.3	更新到 Xcode 26.3+
工具调用缓慢/卡住	项目索引规模较大	等待 Xcode 完成索引

Xcode 内置助手配置

Xcode 还支持为其内置助手配置 MCP 服务。配置文件位于：

~/Library/Developer/Xcode/CodingAssistant/codex
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig

这些配置用于设置 Xcode 的内部助手，与外部 MCP 客户端配置相互独立。

资源

文档：/xcode/mcp-server

Skills：axiom-xcode-mcp-tools、axiom-xcode-mcp-ref