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/claude_desktop_config.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 workspace_list to see what is available, then workspace_connect 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

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

    workspace_connect
        Connects the manager to a specific Xcode workspace or project.
        workspace_id 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.

    workspace_disconnect
        Tears down the active workspace session. Category B through F tools return an
        error until workspace_connect 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

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

    test_run_some
        Runs a specific subset of tests by target and identifier.
        Pass an array of objects with target_name and test_identifier.

    test_list
        Lists all discoverable tests in the active test plan.


Category D  File Operations

    file_read       Read a file by Xcode project path.
    file_write      Create or overwrite a file.
    file_update     Replace an exact string inside a file.
    file_remove     Remove a file or directory from the project.
    file_move       Move or rename a file in the project navigator.
    file_list       List files and directories at a project path.
    dir_make        Create a directory or group.
    file_glob       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).

    preview_render
        Builds and renders a SwiftUI Preview and waits until a snapshot is available.
        Accepts source_file_path and optional preview_index (default 0).

    issues_in_file
        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 MCP_XCODE_PID 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 workspace_connect with a specific
workspace_id 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