XC-MCP

An MCP server that lets AI agents build, run and drive iOS apps — without drowning in Xcode's output.

XC-MCP wraps xcodebuild, simctl and idb as 77 tools. Its job is not just to expose those commands but to make their output fit in a model's context: summaries first, full detail on demand, and the accessibility tree instead of screenshots wherever the app allows it.

---

Why it exists

Xcode tooling produces output at a scale no context window survives. Measured against a real app (Grapla, Xcode 27, iPhone 17 Pro simulator):

Operation	Raw output	XC-MCP response	Reduction
One incremental xcodebuild build	1.67 MB · ~419,000 tokens	1.1 KB · ~285 tokens	~1,470×
xcrun simctl list --json	131 KB · ~32,800 tokens	1.5 KB · ~370 tokens	~90×
One crash report (.ips)	10.7 KB	1.4 KB summary	~7.5×

A single raw build log would overflow a 200k-token context on its own. The full output is never thrown away: it is cached and returned as an MCP resource link, so an agent can drill into the exact errors it needs.

---

Quick start

Claude Code:

claude mcp add xc-mcp -- npx -y xc-mcp

Codex CLI:

codex mcp add xc-mcp -- npx -y xc-mcp

or add it to ~/.codex/config.toml directly:

[mcp_servers.xc-mcp]
command = "npx"
args = ["-y", "xc-mcp"]

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Then ask your agent to build and run your app. rtfm({}) lists the tool categories.

---

Requirements

Requirement	Version	Needed for
macOS	13+	everything
Node.js	20+ (CI tests 22 and 24)	running the server
Xcode + Command Line Tools	15+ (26+ for iOS 26/27 simulators)	xcodebuild, simctl
idb CLI + companion	1.5.1+	every idb-* tool: tapping, typing, accessibility

xcode-select --install

# idb — required for all UI automation
brew tap facebook/fb
brew install facebook/fb/idb-companion facebook/fb/idb-cli

brew install idb-companion no longer works — it moved from Homebrew core to Meta's facebook/fb tap.

Run idb-doctor whenever UI automation misbehaves. It checks the CLI, the companion version, the Xcode framework layout, and stale companion registrations.

Xcode 27

idb-companion must be 1.5.1 or newer. Xcode 27 moved SimulatorKit.framework, and older companions fail silently: the accessibility tree reads correctly and every tap reports success, while the simulator discards the events. idb-ui-tap, idb-ui-gesture and idb-ui-input detect this and refuse to run rather than pretend.

brew upgrade facebook/fb/idb-companion
brew list --versions idb-companion   # expect >= 1.5.1

• There is no Simulator.app — Xcode 27 replaced it with DeviceHub.app. simctl-boot with openGui opens whichever this Xcode ships.
• If every idb call fails with Connection refused, a dead companion is still registered in /tmp/idb/state. Run idb disconnect <udid>; idb-doctor detects this.

---

How it works

Summaries first, detail on demand