If you’ve spent any amount of time with Claude Code on a project for Apple’s various platforms, then you’ve probably hit a wall. Claude is genuinely good at Swift. It understands SwiftUI, it can reason through Swift Concurrency, and it’ll happily refactor a view model while you grab your morning cup of coffee.

But the moment it needs to know whether that code actually builds, things get a little clunky. It’ll begin to shell out to xcodebuild, then parses a wall of log output, guesses at the right scheme and destination, and occasionally edits a file that Xcode doesn’t even know is part of the project.
In other words, Claude can write the code, but it can’t see Xcode — at least, not until recently.

That changed when Apple started shipping its own Model Context Protocol (MCP) server inside Xcode. It arrived with Xcode 26.3 earlier this year, and it grew up considerably in Xcode 27. With a couple minutes of setup, Claude Code running in your terminal can talk directly to the same Xcode you already have open: building, running the project and tests, reading the navigator issues, rendering SwiftUI previews, and a whole lot more.

In this post, I’ll walk through why you’d want to set this up, how to turn it on in Xcode, how to wire it up to Claude Code from the command line, and more.

What is the Xcode MCP Server, Anyway?
MCP is an open standard that lets AI agents call tools exposed by other applications. Instead of an agent scraping output from command line tools, the application describes a set of structured tools (e.g., “build the project,” “list the tests,” “render this preview”) and the agent calls them directly, getting structured results back.

Xcode’s implementation is exposed through a small binary called mcpbridge, which you invoke with xcrun mcpbridge. Your agent speaks MCP to the bridge, and the bridge speaks to the running Xcode process over XPC through interprocess communication. The important bit: It’s talking to your copy of Xcode, with your open workspace, active scheme, and selected run destination. There’s no separate headless build world to keep in sync.

It speaks through this chain:
Claude Xcode ⇄ MCP ⇄ xcrun ⇄ mcpbridge ⇄ XPC ⇄ Xcode

Why You’d Want It
You might be thinking, “Claude Code already runs xcodebuild just fine. Why bother?” While that’s a fair question, here’s exactly why you want to use this.

It works with Xcode’s understanding of your project, not just the file system. The file tools operate on the project navigator, not raw directories. When Claude creates a new Swift file through the MCP server, Xcode adds it to the project. No more “the file exists but isn’t in the target” surprises, and no more agents mucking around the project.pbxproj, potentially causing conflicts.

Builds and tests return structured results. Instead of piping thousands of lines of build logs into the conversation, Claude can build with the active scheme and then ask for just the errors (or warnings) it cares about. Test runs come back per-test, with paths to the full summary and the .xcresult bundle if it needs to dig deeper. That’s faster, more accurate, and a lot easier on your token budget.

It can see what you see. Claude can read the Issue Navigator, pull fresh diagnostics for a single file, and check which file you have open in the editor. When you say “fix the warnings in this file,” it knows which file you mean.

SwiftUI previews become a feedback loop. This is the one that usually sells everyone. Claude can render a SwiftUI preview and get back an image so it can make a layout change, look at the result, and iterate — without you clicking through the canvas. In Xcode 27, it can even render previews in a specific localization or step through a widget’s timeline, all through the MCP.

Xcode 27 turned it into a driver’s seat. The original 26.3 release shipped with around 20 tools focused mainly on files, builds, tests, diagnostics, and previews. Xcode 27 more than doubled that. Agents can now switch schemes and run destinations, run and stop the app, read console and OSLog output, send LLDB commands to an attached debugger, edit build settings, entitlements, and Info.plist keys, add new targets from templates, work with strings catalogs, and even pull top crash signatures and field performance data from your shipping apps.
That last one, by the way, is surprisingly good. You can now start your morning with “What’s our top crash this week, and where do you think it’s coming from?” and fix crashes quicker than ever before.

You keep your terminal workflow. Xcode now has its own built-in coding assistant with Claude available right in the IDE, and it’s great. But a lot of us live in the terminal with Claude Code: our own CLAUDE.md files, our own skills and plugins, and our own hooks for custom slash commands. The MCP server lets you keep all of that and still give Claude first-class access to Xcode without the need to use Xcode’s chat interface.

Setting It Up
Step 1: Enable external agent access in Xcode
Out of the box, Xcode doesn’t let outside agents connect. You need to flip one switch first:

1. Open Xcode, then the project you want to work with
2. Choose Xcode | Settings (or press Command + ,).
3. Select Intelligence in the sidebar.
4. Under Model Context Protocol, turn on Allow external agents to use Xcode tools.

Note: If you’re still on Xcode 26.3, the toggle is labeled “Xcode Tools” under the same Model Context Protocol section. Same switch, different name.
This is the step a lot of people miss. If this setting is off, mcpbridge may still connect, but your agent won’t get any useful tools back. If Claude Code reports that it’s connected to the server but can’t seem to do anything, check this setting first.

You’ll also want to make sure that the project you want Claude to work on is open in Xcode. The bridge attaches to a running Xcode with a real workspace open.

Step 2: Add the Xcode MCP server to Claude Code
Now hop over to the terminal. Claude Code’s claude mcp add command registers the server.

The basic version looks like this:
claude mcp add --transport stdio xcode -- xcrun mcpbridge

Let’s break that down:

• --transport stdio tells Claude Code to launch the server as a local process and talk to it over standard input/output.
• xcode is the name you’re giving the server. Call it whatever you like; this is what shows up in Claude Code’s server list.
• Everything after the -- is the command Claude Code runs to start the server: xcrun mcpbridge.

By default, claude map add registers the server for the current project only. If you want Xcode available in every Apple-platforms-based project, you can add it at the user scope instead:
claude mcp add --transport stdio xcode -s user -- xcrun mcpbridge

If you’d rather share the configuration with your team through the repo, use -s project, which writes it to a .mcp.json file at the project root that you can commit alongside your code.

Step 3: Verify the Connection
Confirm the server is registered with this command:
claude mcp list

You should see xcode in the output. Start a Claude Code session in your project directory and run /mcp to check the server’s status and see the tools it exposes.

The first time Claude Code connects, Xcode will put up an alert asking whether you want to allow the agent to access Xcode. Approve it, and you’re in business.

Xcode will also let you know when an external agent is connected and when it’s actively doing work, which I appreciate. It’s nice to have a visual signal when something other than me is doing work in Xcode.

A Quick Smoke Test
Once you’re connected, try something like:
“Build the project with the current scheme. If there are any errors or warnings, summarize them and propose fixes.”

Or, if you’re working in SwiftUI:
“Render the preview for ProfileView.swift, then tighten up the spacing in the header so it matches the rest of the app.”

Watch Claude call the Xcode tools rather than trying to work with xcodebuild directly. That’s how you know it’s working.

Tips, Gotchas, and Troubleshooting
“Unable to find utility mcpbridge.” This almost always means your developer directory points at the Command Line Tools rather than at a full Xcode install. Fix it with:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

Then run xcrun --find mcpbridge to confirm it resolves to a path.

Multiple Xcodes running? If you’ve got a release Xcode and a beta Xcode open side by side (let’s be honest, during the summer we’re all doing it), mcpbridge connects to the one selected by xcode-select. To target a specific instance, find its process ID and pass it through the MCP_XCODE_PID environment variable like this:
pgrep -x Xcode
claude mcp add --transport stdio xcode-beta -s user -- env MCP_XCODE_PID=12345 xcrun mcpbridge

Keep in mind that the PID changes every time you relaunch Xcode, so this is better for a working session than a permanent configuration.

Multiple workspaces open? Most tools accept an optional workspace tab identifier. In Xcode 27 you can omit it when only one workspace is open, but if you have several open, Claude may first ask Xcode for a list of windows so it knows which one to target. That’s expected behavior, not a bug.

Mind your context window. Every connected MCP server adds its own tool definitions to each Claude Code session, and Xcode 26’s server has a lot of tools. If you’re doing non-Xcode work in the same directory, consider registering the server at project scope only for your app repos, or toggling it off when you don’t need it.

Headless mode is worth watching. Xcode 27 also introduced a preview of a headless MCP server (xcrun mcp-server) that runs without an open Xcode window and can grant code-signed agents longer-lived, folder-scoped permissions instead of prompting every single time. It’s aimed at unattended and Continuous Integration-style setups. Apple is clearly labeling it as early, and it involves sudo and other permissions decisions that you’ll need to figure out for your setup, so it’s best to read up on that before adopting it on your developer machine.

Review what it does. The MCP server can add entitlements, change build settings, create targets, and delete files. That’s the whole point, but it’s also a good reason to keep your work in version control and actually read the diffs before you commit. An agent with real tools is an agent that can make real mistakes, just like humans. Verify and review work before committing.

Claude Desktop. Not everyone lives in the terminal. If you’d rather use the Claude Desktop app, it can talk to the same Xcode MCP server. (Thanks to Greg McLaughlin here at MartianCraft for testing this setup.)

1. Turn on Allow external agents to use Xcode tools in Xcode, just like in Step 1.
2. In Claude Desktop, choose Claude > Settings from the menu bar, select Developer in the sidebar, and click Edit Config. This opens (or creates) ~/Library/Application Support/Claude/claude_desktop_config.json.
3. Add an Xcode entry under mcpServers:

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

If the file already has other settings in it, don’t paste a second set of outer braces. Add the “mcpServers” block inside the existing ones, ideally at the top (Claude Desktop rewrites the file and moves it there anyway), and keep a comma between it and whatever follows. If you already have an mcpServers block, just add the xcode entry to it.

1. Quit Claude Desktop completely with Command + Q and reopen it. Closing the window isn’t enough, because the config is only read at launch.
2. Open your project in Xcode, then start a new chat in Claude Desktop. Click the + button in the message box, hover over Connectors, and choose Manage connectors. You should see Xcode in the list, with its tools.

The first time Claude connects, Xcode asks whether to allow it, just like with Claude Code. Approve it, and the smoke test prompts above work the same way.

If Xcode doesn’t show up, check the logs in ~/Library/Logs/Claude. mcp.log covers connection failures, and mcp-server-xcode.log shows what the bridge itself printed.

Wrapping Up
For a long time, using AI agents on Apple platform projects meant working around Xcode. With the Xcode MCP server, Claude Code finally works with it: It builds the way Xcode builds, tests the way Xcode tests, and sees the same issues, previews, and project structure that you do. The setup is one checkbox and one terminal command, and the payoff is that an agent can spend less time guessing and more time actually getting work done.

Here at MartianCraft, we’ve been building for Apple platforms since the very beginning, and we’ve been folding these agentic workflows into client projects for years, figuring out the best ways to use them to ship real apps for real clients.

If you’re trying to figure out how AI fits into your own iOS, iPadOS, or macOS development process, or if you just need a team of trusted engineers who know Xcode inside and out, get in touch with us. We’d love to help you understand this new world of software engineering.