axiom-xcode-mcp-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode MCP Setup

Xcode MCP 设置

Prerequisites

前提条件

Xcode 26.3+ with MCP support
macOS with Xcode installed and running
At least one project/workspace open in Xcode

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

Step 1: Enable MCP in Xcode

步骤1：在Xcode中启用MCP

Open Xcode Settings (Cmd+,)
Go to Intelligence tab
Check Enable Model Context Protocol
Ensure Xcode Tools toggle is ON

Without this toggle,

xcrun mcpbridge

connects but returns no tools.

打开Xcode 设置（Cmd+,）
进入**智能助手（Intelligence）**标签页
勾选启用模型上下文协议（Model Context Protocol）
确保Xcode工具开关处于开启状态

如果没有打开这个开关，

xcrun mcpbridge

可以连接但不会返回任何工具。

Step 2: Connect Your MCP Client

步骤2：连接你的MCP客户端

Claude Code

bash

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

Verify:

claude mcp list

should show

xcode

server.

bash

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

验证：

claude mcp list

应该显示

xcode

服务器。

Codex

bash

codex mcp add xcode -- xcrun mcpbridge

bash

codex mcp add xcode -- xcrun mcpbridge

Cursor

Create or edit

.cursor/mcp.json

in your project root:

json

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

Cursor-specific note: Cursor is a strict MCP client. Xcode's mcpbridge omits

structuredContent

when tools declare

outputSchema

, which violates the MCP spec. If Cursor rejects responses, use XcodeMCPWrapper as a proxy:

json

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

在项目根目录创建或编辑

.cursor/mcp.json

：

json

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

Cursor专属说明：Cursor是严格的MCP客户端。Xcode的mcpbridge在工具声明

outputSchema

时会省略

structuredContent

，这违反了MCP规范。如果Cursor拒绝响应，请使用XcodeMCPWrapper作为代理：

json

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

VS Code + GitHub Copilot

Create or edit

.vscode/mcp.json

json

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

创建或编辑

.vscode/mcp.json

：

json

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

Gemini CLI

bash

gemini mcp add xcode -- xcrun mcpbridge

bash

gemini mcp add xcode -- xcrun mcpbridge

Step 3: Verify Connection

步骤3：验证连接

After configuration, call

XcodeListWindows

(no parameters). You should see:

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

If you see an empty list, ensure a project is open in Xcode.

配置完成后，调用

XcodeListWindows

（无参数）。你应该看到：

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

如果看到空列表，请确保Xcode中打开了一个项目。

Permission Dialog

权限对话框

When an MCP client first connects, Xcode shows a permission dialog:

Identifies the connecting process by PID
Asks to allow MCP tool access
Must be approved in Xcode's UI (not terminal)

PID-based approval: Permission is granted per-process. If the client restarts (new PID), you'll see the dialog again. This is expected behavior.

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

通过PID识别连接的进程
请求允许访问MCP工具
必须在Xcode的UI中批准（而非终端）

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

Multi-Xcode Targeting

多Xcode实例目标定位

When multiple Xcode instances are running:

当运行多个Xcode实例时：

Auto-Detection (default)

自动检测（默认）

mcpbridge auto-selects using this fallback:

If exactly one Xcode process is running → uses that
If multiple → uses the one matching
```
xcode-select
```
If none → exits with error

mcpbridge会通过以下回退逻辑自动选择：

如果恰好有一个Xcode进程在运行 → 使用该实例
如果有多个 → 使用与
```
xcode-select
```
匹配的实例
如果没有 → 报错退出

Manual PID Selection

手动选择PID

Set

MCP_XCODE_PID

to target a specific instance:

bash

undefined

设置

MCP_XCODE_PID

以指定目标实例：

bash

undefined

Find Xcode PIDs

查找Xcode的PID

pgrep -x Xcode

Claude Code with specific PID

使用指定PID连接Claude Code

claude mcp add --transport stdio xcode -- env MCP_XCODE_PID=12345 xcrun mcpbridge

undefined

claude mcp add --transport stdio xcode -- env MCP_XCODE_PID=12345 xcrun mcpbridge

undefined

Session ID (optional)

会话ID（可选）

MCP_XCODE_SESSION_ID

provides a stable UUID for tool sessions, useful when tracking interactions across reconnections.

MCP_XCODE_SESSION_ID

为工具会话提供稳定的UUID，在跨重连接跟踪交互时非常有用。

Troubleshooting

故障排查

dot

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)"];
}

dot

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)"];
}

Common Issues

常见问题

Symptom	Cause	Fix
"Connection refused"	Xcode not running or MCP toggle off	Launch Xcode, enable MCP in Settings > Intelligence
tools/list returns empty	No project open, or permission not granted	Open a project, check for permission dialog in Xcode
Tools target wrong project	Multiple Xcode windows, wrong tab	Call `XcodeListWindows` , use correct `tabIdentifier`
Repeated permission prompts	Client restarted (new PID)	Expected behavior — approve each time
Cursor/strict client errors	Missing `structuredContent` in response	Use XcodeMCPWrapper as proxy
"No such command: mcpbridge"	Xcode < 26.3	Update to Xcode 26.3+
Slow/hanging tool calls	Large project indexing	Wait for Xcode indexing to complete

症状	原因	解决方法
"连接被拒绝"	Xcode未运行或MCP开关未开启	启动Xcode，在设置>智能助手中启用MCP
tools/list返回空	没有打开项目，或未授予权限	打开一个项目，检查Xcode中的权限对话框
工具指向错误的项目	多个Xcode窗口，标签页错误	调用 `XcodeListWindows` ，使用正确的 `tabIdentifier`
重复出现权限提示	客户端重启（新的PID）	预期行为——每次都需要批准
Cursor/严格客户端报错	响应中缺少 `structuredContent`	使用XcodeMCPWrapper作为代理
"没有找到命令: mcpbridge"	Xcode版本低于26.3	升级到Xcode 26.3+
工具调用缓慢/挂起	大型项目正在索引	等待Xcode完成索引

Xcode Built-in Assistant Config

Xcode内置助手配置

Xcode also supports MCP servers for its built-in assistants. Config files live at:

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

These are for configuring Xcode's internal assistant, separate from external MCP client setup.

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

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

这些用于配置Xcode的内部助手，与外部MCP客户端设置是分开的。

Resources

资源

Docs: /xcode/mcp-server

Skills: axiom-xcode-mcp-tools, axiom-xcode-mcp-ref

文档：/xcode/mcp-server

技能：axiom-xcode-mcp-tools, axiom-xcode-mcp-ref