Xcode Mcp Manager

xcode-mcp-manager

Version 0.0.1 | MIT License | Andrei Blinov

A Claude Code MCP server that keeps Claude Code connected to Xcode at all times. It automatically detects when Xcode is running, spawns Apple's xcrun mcpbridge, and dismisses the Xcode permission dialog - so Claude Code gains full access to your Xcode project without any manual steps.

OVERVIEW

The official Xcode MCP server (xcrun mcpbridge, shipped with Xcode 26.3) requires Xcode to be running before you start Claude Code. If you launch Claude Code first, open a new project later, or switch projects mid-session, the MCP connection is simply not there.

This manager fixes the ordering problem and the permission dialog problem in one shot.

It runs as a persistent MCP server alongside Claude Code. A background loop polls for Xcode every two seconds. The moment Xcode appears - before or after Claude Code starts, any project, any time - the manager spawns xcrun mcpbridge, performs the initialize handshake, and starts accepting tool calls. If Xcode closes and reopens, it reconnects automatically. No restart of Claude Code is needed.

The permission dialog Xcode shows on every new MCP connection is auto-dismissed via AppleScript. Without that, a human has to click Allow before any tool call can proceed, which makes unattended agentic tasks impossible.

Tested on Xcode Version 26.3 (17C529) and Claude Code Version 2.1.79.

REQUIREMENTS

macOS only. xcrun mcpbridge does not exist on other platforms.

Xcode 26.3 or later. Xcode 26.3 is the first version that ships xcrun mcpbridge. Install it via the Apple Developer Program if your App Store Xcode is on an earlier release. Earlier Xcode versions will not work.

Xcode Tools enabled. In Xcode, choose Xcode > Settings and select Intelligence in the sidebar. Under Model Context Protocol, toggle Xcode Tools on. Without this, xcrun mcpbridge will not accept connections from external agents.

Node.js 22 or later.

System Events automation permission for the terminal that runs Claude Code. macOS prompts for this the first time autoAllowXcodeDialog runs. Grant it under System Settings > Privacy and Security > Automation.

INSTALLATION

npm install -g xcode-mcp-manager

Or use npx directly in the Claude Code MCP config without a separate install step (see Configuration below). npx will fetch and cache the package on first run.

CONFIGURATION

Add an entry to your Claude Code MCP configuration. The project-level file is .mcp.json in your project root. The global file is ~/.claude/claudedesktopconfig.json.

{ "mcpServers": { "xcode": { "command": "npx", "args": ["-y", "xcode-mcp-manager"] } } }

Alternatively, register the server from the command line without editing any file:

claude mcp add xcode-mcp-manager -- npx -y xcode-mcp-manager

This writes the same entry to your Claude Code configuration automatically. To verify the registration, run:

claude mcp list

Start Claude Code. The manager starts polling for Xcode immediately on launch.

Open any Xcode project at any point. Within a few seconds the bridge is live. Call workspacelist to see what is available, then workspaceconnect to attach to a project. Use workspace_id "auto" to connect to whichever Xcode window is currently in front.

TOOLS

24 tools are registered. Category A tools are always available once the bridge is connected. Category B through F tools require a prior workspace_connect call.

Category A Workspace Lifecycle

workspacelist Discovers all Xcode workspaces and projects currently open on this machine. Returns a list of workspace descriptors with IDs for use in workspaceconnect.

workspaceconnect Connects the manager to a specific Xcode workspace or project. workspaceid can be a value from workspace_list or the string "auto". "auto" picks the frontmost Xcode window automatically.

workspace_status Reports the current connection state, bridge liveness, uptime, and reconnect count. Does not change anything.

workspacedisconnect Tears down the active workspace session. Category B through F tools return an error until workspaceconnect is called again.

Category B Build and Diagnostics

build Builds the connected workspace using the currently active scheme. Waits for the build to complete before returning.

issues Lists issues currently visible in the Xcode Issue Navigator. Accepts optional severity, glob, and pattern filters.

build_log Returns the log from the current or most recently completed build. Accepts optional severity, glob, and pattern filters.

Category C Test Execution

testrunall Runs all tests in the active scheme's active test plan. Waits for completion. Can take several minutes on large projects.

testrunsome Runs a specific subset of tests by target and identifier. Pass an array of objects with targetname and testidentifier.

test_list Lists all discoverable tests in the active test plan.

Category D File Operations

fileread Read a file by Xcode project path. filewrite Create or overwrite a file. fileupdate Replace an exact string inside a file. fileremove Remove a file or directory from the project. filemove Move or rename a file in the project navigator. filelist List files and directories at a project path. dirmake Create a directory or group. fileglob Find files matching a wildcard pattern. file_grep Search file contents by regular expression.

Category E Code Intelligence

snippet_run Builds and executes a Swift code snippet in the context of a source file. Accepts an optional timeout in seconds (default 120).

previewrender Builds and renders a SwiftUI Preview and waits until a snapshot is available. Accepts sourcefilepath and optional previewindex (default 0).

issuesinfile Retrieves current compiler diagnostics for a single file.

docs_search Searches Apple Developer Documentation using semantic matching. Accepts a query string and optional list of framework names to search within.

Category F Navigation

windows_list Lists all current Xcode windows with workspace information and active status.

HOW IT WORKS

The manager spawns as an MCP server over stdio, which is how Claude Code communicates with all MCP servers.

Internally a BridgeActor runs a polling loop using pgrep to detect a running Xcode process. When Xcode appears, the actor calls xcrun mcpbridge passing the Xcode PID via the MCPXCODEPID environment variable. It then performs the JSON-RPC 2.0 initialize handshake defined by the MCP protocol spec 2024-11-05.

In parallel, autoAllowXcodeDialog runs an AppleScript loop for up to 18 seconds after each spawn attempt, clicking the Allow button on any Xcode permission window it finds. This is what makes the connection fully unattended.

Once the bridge is connected, incoming tool calls from Claude Code are routed through BridgeCaller, which injects the current tabIdentifier into every request that requires it. The tabIdentifier is obtained from workspace_connect and cached in WorkspaceState for the duration of the session.

A PingController sends tools/list every 60 seconds as a keepalive. If no response arrives within 75 seconds the bridge is considered dead and the reconnect cycle begins. A Watchdog timer fires every 5 seconds and logs a stall warning if no activity has been seen for 15 seconds.

If Xcode quits, the liveness check (run every 2 seconds) detects the dead PID and tears down the bridge cleanly. The actor re-enters the polling loop and reconnects when Xcode starts again.

NOTES

System Events permission. macOS will block the AppleScript auto-allow on first run. Grant Automation access for your terminal app under System Settings > Privacy and Security > Automation. Without this the permission dialog will have to be clicked manually on each new connection.

xcrun mcpbridge is Apple's tool, not bundled here. xcode-mcp-manager is a supervisor that manages the connection lifecycle. The actual Xcode integration is provided by xcrun mcpbridge in your Xcode installation.

One Xcode process at a time. The manager connects to the first Xcode PID it finds. If multiple Xcode processes are running, call workspaceconnect with a specific workspaceid from workspace_list to select the right one.

Permission dialog appears per-process. Every time xcrun mcpbridge is respawned (for example after Xcode restarts) a new permission dialog appears. The auto-allow mechanism handles this but requires the Automation permission described above.

REFERENCES

Apple Developer Documentation Giving external agentic coding tools access to Xcode https://developer.apple.com/documentation/Xcode/giving-agentic-coding-tools-access-to-xcode

Apple describes the general approach as: configure the agentic coding tool to access Xcode capabilities through the Model Context Protocol (MCP) server that Xcode provides. Open your project in Xcode and begin entering prompts in the agentic coding tool that utilizes Xcode. Xcode alerts you when the external agent connects to Xcode and when it is active.

xcode-mcp-manager automates the connection lifecycle that Apple's documentation describes, removing the manual sequencing requirement and the per-spawn permission dialog.

AUTHOR

Andrei Blinov https://github.com/ndrblinov/xcode-mcp-manager

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ndrblinov
• Source: ndrblinov/xcode-mcp-manager
• License: MIT
• Homepage: https://www.npmjs.com/package/xcode-mcp-manager

Install and usage instructions live in the source repository linked above.