Xcode MCP Setup

Prerequisites

• Xcode 26.3+ with MCP support

• macOS with Xcode installed and running

• At least one project/workspace open in Xcode

Step 1: Enable MCP in Xcode

• 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.

Step 2: Connect Your MCP Client

Claude Code

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

Verify: claude mcp list should show xcode server.

Codex

codex mcp add xcode -- xcrun mcpbridge

Cursor

Create or edit .cursor/mcp.json in your project root:

{ "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:

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

VS Code + GitHub Copilot

Create or edit .vscode/mcp.json :

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

Gemini CLI

gemini mcp add xcode -- xcrun mcpbridge

Step 3: Verify Connection

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.

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.

Multi-Xcode Targeting

When multiple Xcode instances are running:

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

Manual PID Selection

Set MCP_XCODE_PID to target a specific instance:

Find Xcode PIDs

pgrep -x Xcode

Claude Code with specific PID

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

Session ID (optional)

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

Troubleshooting

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 Built-in Assistant Config

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.

Resources

Docs: /xcode/mcp-server

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