Skip to content
Back to search

xc-mcp

XCode CLI & Simulator MCP. Progressive disclosure of tool responses reduces context and token waste. Lets AI agents build, run and drive iOS apps — without drowning in Xcode's output.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conorluddy--xc-mcp/badge.svg)](/listings/conorluddy--xc-mcp)

HTML

<a href="/listings/conorluddy--xc-mcp"><img src="/api/listings/conorluddy--xc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 413 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # XC-MCP
  2. [![npm version](https://img.shields.io/npm/v/xc-mcp.svg)](https://www.npmjs.com/package/xc-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/xc-mcp.svg)](https://www.npmjs.com/package/xc-mcp)
  4. [![codecov](https://codecov.io/gh/conorluddy/xc-mcp/graph/badge.svg?token=4CKBMDTENZ)](https://codecov.io/gh/conorluddy/xc-mcp)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. **An MCP server that lets AI agents build, run and drive iOS apps — without drowning in Xcode's output.**
  7. XC-MCP wraps `xcodebuild`, `simctl` and `idb` as 81 tools. Its job is not just to expose those
  8. commands but to make their output fit in a model's context: summaries first, full detail on demand,
  9. and the accessibility tree instead of screenshots wherever the app allows it.
  10. ---
  11. ## Why it exists
  12. Xcode tooling produces output at a scale no context window survives. Measured against a real app
  13. (Grapla, Xcode 27, iPhone 17 Pro simulator):
  14. | Operation | Raw output | XC-MCP response | Reduction |
  15. |---|---|---|---|
  16. | One incremental `xcodebuild build` | 1.67 MB · ~419,000 tokens | 1.1 KB · ~285 tokens | **~1,470×** |
  17. | `xcrun simctl list --json` | 131 KB · ~32,800 tokens | 1.5 KB · ~370 tokens | **~90×** |
  18. | One crash report (`.ips`) | 10.7 KB | 1.4 KB summary | **~7.5×** |
  19. A single raw build log would overflow a 200k-token context on its own. The full output is never
  20. thrown away: it is cached and returned as an MCP resource link, so an agent can drill into the
  21. exact errors it needs.
  22. ---
  23. ## Quick start
  24. **Claude Code:**
  25. ```bash
  26. claude mcp add xc-mcp -- npx -y xc-mcp
  27. ```
  28. **Codex CLI:**
  29. ```bash
  30. codex mcp add xc-mcp -- npx -y xc-mcp
  31. ```
  32. or add it to `~/.codex/config.toml` directly:
  33. ```toml
  34. [mcp_servers.xc-mcp]
  35. command = "npx"
  36. args = ["-y", "xc-mcp"]
  37. ```
  38. **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  39. ```json
  40. {
  41. "mcpServers": {
  42. "xc-mcp": { "command": "npx", "args": ["-y", "xc-mcp"] }
  43. }
  44. }
  45. ```
  46. Then ask your agent to build and run your app. `rtfm({})` lists the tool categories.
  47. ---
  48. ## Requirements
  49. | Requirement | Version | Needed for |
  50. |---|---|---|
  51. | macOS | 13+ | everything |
  52. | Node.js | 20+ (CI tests 22 and 24) | running the server |
  53. | Xcode + Command Line Tools | 15+ (26+ for iOS 26/27 simulators) | `xcodebuild`, `simctl` |
  54. | `idb` CLI + companion | **1.5.1+** | every `idb-*` tool: tapping, typing, accessibility |
  55. ```bash
  56. xcode-select --install
  57. # idb — required for all UI automation
  58. brew tap facebook/fb
  59. brew install facebook/fb/idb-companion facebook/fb/idb-cli
  60. ```
  61. > `brew install idb-companion` no longer works — it moved from Homebrew core to Meta's
  62. > `facebook/fb` tap.
  63. **Run `idb-doctor` whenever UI automation misbehaves.** It checks the CLI, the companion version,
  64. the Xcode framework layout, stale companion registrations, CLI/companion version mismatches, and the axbridge guest needed by deep reads.
  65. ### Xcode 27
  66. **`idb-companion` must be 1.5.1 or newer.** Xcode 27 moved `SimulatorKit.framework`, and older
  67. companions fail silently: the accessibility tree reads correctly and every tap reports success,
  68. while the simulator discards the events. `idb-ui-tap`, `idb-ui-gesture` and `idb-ui-input` detect
  69. this and refuse to run rather than pretend.
  70. ```bash
  71. brew upgrade facebook/fb/idb-companion
  72. brew list --versions idb-companion # expect >= 1.5.1
  73. ```
  74. - **There is no `Simulator.app`** — Xcode 27 replaced it with `DeviceHub.app`. `simctl-boot` with
  75. `openGui` opens whichever this Xcode ships.
  76. - If every `idb` call fails with `Connection refused`, a dead companion is still registered in
  77. `/tmp/idb/state`. Run `idb disconnect <udid>`; `idb-doctor` detects this.
  78. ---
  79. ## How it works
  80. ### Summaries first, detail on demand
  81. Tools that produce large output return a summary plus an ID. The full output stays in a 30-minute
  82. cache and is exposed two ways: an MCP resource at `xcmcp://response/{id}`, and the matching
  83. `*-get-details` tool for clients without resource support.
  84. ```typescript
  85. xcodebuild-build({ projectPath: "./MyApp.xcodeproj", scheme: "MyApp" })
  86. // → { buildId, success: false, errorCount: 3, warningCount: 1, durationMs: 18000 }
  87. xcodebuild-get-details({ buildId, detailType: "errors-only" })
  88. // → the three errors, not the 419k-token log
  89. ```
  90. ### The accessibility tree before screenshots
  91. For UI automation, reading the accessibility tree is cheaper and faster than sending an image, and
  92. it gives exact coordinates instead of visual estimates. Measured on the same screen:
  93. | Approach | Response | Latency |
  94. |---|---|---|
  95. | `idb-ui-find-element` | ~450 tokens of JSON | ~270 ms |
  96. | `screenshot` (half size) | ~22.5 KB image | ~1,700 ms |
  97. The first idb call in a session takes several seconds while the target cache warms.
  98. This only works when the app is accessible — which is the point. An app VoiceOver can navigate is
  99. an app an agent can navigate. `accessibility-quality-check` says which path to take;
  100. `accessibility-audit` says what to fix.
  101. ```typescript
  102. idb-ui-find-element({ query: "Sign In" })
  103. // → { centerX: 201, centerY: 572, visible: true }
  104. idb-ui-tap({ x: 201, y: 572 })
  105. ```
  106. **Coordinates are not always tappable.** The tree reports frames in scrolled-content space, so an
  107. element can sit below the fold. Every match carries `visible` and, when off-screen, an
  108. `offscreenReason` naming the gesture that brings it into view.
  109. ### Simulator automation in v5
  110. - `idb-semantic-action` presses a uniquely identified control or replaces a field value with read-back verification. Use `expect` to guard a toggle's current value. Secure field values cannot be verified.
  111. - `idb-ui-find-element` supports exact, type, identifier and index selection. `workflow-tap-element` uses accessibility presses for single matching controls.
  112. - `idb-ui-describe({ operation: "all", deep: true })` opts into axbridge for web content and alerts. This enables device accessibility automation mode, which idb does not restore. Deep web frames are unsuitable for coordinate taps.
  113. - `idb-ui-gesture` adds scroll (content direction), refresh, label-based drag, pinch, long press, multi-tap, rotation and shake. Newer accessibility actions and gestures require idb CLI and companion 1.7+.
  114. - `app-state-capture({ outputDir: "/tmp/app-captures" })` creates a bundle of screenshot, accessibility tree, recent logs, device metadata and summary files. Individual artifact failures are reported.
  115. See [the parity audit](docs/simulator-skill-parity.md) for capability mappings and verification limits.
  116. ### iPhone Duo
  117. Use `simctl-duo` with an explicit booted Duo UDID and `operation: "state"` to read
  118. the hinge angle and enumerate displays. Set `operation: "hinge"` with `pose: "closed"`,
  119. `"partial"`, `"open"`, or an explicit `angle` in degrees. Use `operation: "rotate"`
  120. with `orientation: "portrait"`, `"landscape"`, `"portrait-upside-down"`, or
  121. `"landscape-flipped"`. Changes verify readback; failures include actionable guidance.
  122. Pass the returned display ID as a string in `display` to `screenshot` or `simctl-io`.
  123. Inactive displays can capture black. Explicit display capture omits unverified coordinate
  124. mapping; idb inner-display touch routing is not supported by this integration.
  125. The small bundled Objective-C helper compiles on first use with the selected Xcode
  126. and is cached under `~/Library/Caches/xc-mcp/duo`. No community CLI is required.
  127. Mechanism research credit: [hinge](https://github.com/artemnovichkov/hinge) and
  128. [duoctl](https://github.com/skarol/duoctl). XC-MCP implements its own focused helper.
  129. These private interfaces are experimental. Replace the internal backend as supported
  130. headless APIs become available and verified; folding and rotation may migrate separately.
  131. An XCTest-only API does not replace this headless workflow.
  132. Example MCP calls (replace `<duo-udid>` with a booted Duo UDID):
  133. ```json
  134. {"name":"simctl-duo","arguments":{"udid":"<duo-udid>","operation":"state"}}
  135. {"name":"simctl-duo","arguments":{"udid":"<duo-udid>","operation":"hinge","pose":"open"}}
  136. {"name":"simctl-duo","arguments":{"udid":"<duo-udid>","operation":"hinge","angle":127}}
  137. {"name":"simctl-duo","arguments":{"udid":"<duo-udid>","operation":"rotate","orientation":"portrait"}}
  138. {"name":"screenshot","arguments":{"udid":"<duo-udid>","display":"3","size":"full"}}
  139. ```
  140. Use the display ID from your own state result; IDs above are examples. Supply exactly
  141. one of `pose` or `angle` for hinge operations. `partial` means 90°. The response includes
  142. `hingeAngle`, `activeScreen`, `displayId`, `rotation`, and the display inventory.
  143. Verified on Xcode 27.1 / iOS 27.1. Rapid rotation can time out even when a paused
  144. sequence succeeds; cover landscape also timed out in live checks. Read the returned
  145. `success` and observed state before proceeding. The five-second polling budget excludes
  146. initial readback and dispatch, so total request time can be longer. See the
  147. [live verification matrix](docs/simulator-skill-parity.md#duo-integration-verification--2026-11-08).
  148. Duo controls are available in default and `--mini` modes, and excluded by `--build-only`.
  149. ## Tools that declare their risk
  150. Every tool carries MCP annotations — `readOnlyHint`, `destructiveHint`, `idempotentHint` — so a
  151. client can ask before running `simctl-erase`, `idb-crash-delete` or `idb-clear-keychain`, and run
  152. `simctl-list` freely. Build, test, audit and crash tools also declare an `outputSchema` and return
  153. validated `structuredContent`.
  154. ---
  155. ## Tools
  156. **81 tools.** [TOOL_SIGNATURES.md](./TOOL_SIGNATURES.md) indexes every tool with its annotations;
  157. parameters come from the server itself via `rtfm({ toolName: "..." })`.
  158. | Area | Tools |
  159. |---|---|
  160. | **Build & test** | `xcodebuild-build`, `-test`, `-clean`, `-list`, `-version`, `-showsdks`, `-get-details`, `-inspect-scheme`, `-validate-capabilities` |
  161. | **Simulators** | `simctl-list`, `-get-details`, `-suggest`, `-health-check`, `-boot`, `-shutdown`, `-create`, `-delete`, `-erase`, `-clone`, `-rename`, `-duo` |
  162. | **Apps** | `simctl-install`, `-uninstall`, `-launch`, `-terminate`, `-openurl`, `-get-app-container`, `-container` |
  163. | **UI automation** | `idb-ui-describe`, `-find-element`, `idb-semantic-action`, `-tap`, `-input`, `-gesture`, `idb-targets`, `idb-list-apps`, `idb-install`, `-uninstall`, `-launch`, `-terminate` |
  164. | **Accessibility** | `accessibility-quality-check`, `accessibility-audit` |
  165. | **Diagnostics** | `idb-doctor`, `idb-crash-list`, `-show`, `-delete`, `hang-start`, `-stop`, `-get-details`, `-list` |
  166. | **Test setup** | `simctl-privacy`, `-push`, `-pbcopy`, `-addmedia`, `-status-bar`, `-stream-logs`, `-appearance`, `-location`, `idb-library`, `idb-simulate-memory-warning`, `idb-clear-keychain`, `idb-xctest-list` |
  167. | **Capture & analysis** | `screenshot`, `simctl-io`, `visual-diff`, `localization-audit`, `xcode-model-inspect` |
  168. | **Workflows** | `workflow-build-and-run`, `workflow-fresh-install`, `workflow-tap-element`, `test-record-step`, `test-record-report`, `app-state-capture` |
  169. | **Cache & docs** | `cache-get-stats`, `-get-config`, `-set-config`, `-clear`, `persistence-enable`, `-disable`, `-status`, `rtfm` |
  170. ---
  171. ## Configuration
  172. | Flag | Effect |
  173. |---|---|
  174. | `--mini`, `-m` | One-line tool descriptions; `rtfm` supplies the detail |
  175. | `--build-only`, `-b` | Registers 18 build-focused tools instead of 81 |
  176. Flags combine: `["-y", "xc-mcp", "--mini", "--build-only"]` — the same `args` array works in Claude Desktop and Codex's `config.toml`. Both matter mainly for clients that
  177. load every tool description upfront; see the history below.
  178. | Environment variable | Default | Controls |
  179. |---|---|---|
  180. | `XC_MCP_CACHE_DIR` | `~/.xc-mcp` (honours `XDG_CACHE_HOME`) | Disk persistence for caches |
  181. | `XC_MCP_HANG_DIR` | `~/.xc-mcp/hang-sessions` | HangBuster capture sessions |
  182. | `XC_MCP_RECORDINGS_DIR` | `~/.xc-mcp/test-recordings` | Test recording reports |
  183. ---
  184. ## How context cost shaped this server
  185. XC-MCP has been rebuilt three times, and each rebuild answered the same question — *what does a tool
  186. cost in context?* — differently, because the answer kept changing underneath it. The tool count
  187. went 51 → 28 → 77, and each time the right number was set by what clients and the protocol could do.
  188. ### v1 · Aug 2025 — 51 tools, every description paid upfront
  189. MCP clients of the time loaded every tool's name, description and input schema when they connected,
  190. and kept them in context for the whole session. Tool count was a tax on context, paid before the
  191. agent did any work.
  192. v1.3.2 cut the tax per tool: descriptions shrank to a few words and the real documentation moved
  193. behind `rtfm`, fetched only when asked for. A separate, smaller `xc-mini-mcp` package was also
  194. published — and reverted shortly after.
  195. ### v2 · Nov 2025 — 28 tools, consolidated into routers
  196. If the count is the tax, cut the count. v2 folded 21 tools into six operation-enum routers —
  197. `simctl-device({ operation: "boot" })` instead of `simctl-boot` — sharing one schema per router.
  198. That bought a debt nobody could see yet. A router is a single tool, so it carries a single
  199. description and a single set of properties for every operation behind it. That cost nothing while
  200. tools had no per-tool properties worth losing.
  201. ### v3 · Nov 2025 — betting on deferred loading
  202. v3 set `defer_loading: true` on every tool, expecting tools to load on demand and baseline cost to
  203. fall toward zero. The goal was right; the mechanism could not work.
  204. `defer_loading` is a field of the **Messages API**. It belongs on tool definitions sent to the model,
  205. alongside the tool-search server tools, and an MCP server has no way to set it. The MCP SDK also
  206. drops unrecognised keys from a tool's registration, so the flag never reached a client — a live
  207. `tools/list` later showed 0 of 77 tools carrying it.
  208. Deferral did arrive, **on the client side**. Clients with tool search, Claude Code among them, began
  209. listing only tool names at startup and fetching a tool's schema when it is first used. No server
  210. flag was involved.
  211. ### v4 · Jun 2026 — 70 tools, routers dissolved
  212. Two developments reversed the v2 trade-off.
  213. - **Client-side tool search made tool count cheap.** With schemas deferred, 77 tools cost roughly
  214. what their names cost — about 1,240 tokens at startup, server instructions included.
  215. - **The protocol gained per-tool metadata.** Revision `2025-03-26` added tool annotations
  216. ([#185](https://github.com/modelcontextprotocol/specification/pull/185)). Revision `2025-06-18`
  217. added structured tool output
  218. ([#371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371)), resource links in
  219. tool results ([#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603)), and
  220. a human-readable `title` ([#663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/663)).
  221. Annotations are precisely what a router cannot express. `simctl-device` hid both `boot`, which is
  222. harmless, and `erase`, which destroys a simulator, behind one tool — so no client could tell them
  223. apart. The routers were dissolved into discrete tools that each declare their own risk and output
  224. shape, and resource links replaced ad-hoc cache IDs as the way to return large output. The server
  225. negotiates protocol `2025-06-18`.
  226. ### v4.1 · Sep 2026 — 71 tools, Xcode 27 readiness
  227. Xcode 27 broke idb in a way that failed silently: older companions read the accessibility tree
  228. correctly but dropped every tap while reporting success. v4.1 added `idb-doctor`, a 1.5.1 companion
  229. floor, and a preflight that makes HID-writing tools refuse to run rather than pretend.
  230. ### v4.2 · Sep 2026 — 77 tools, tested against a real app
  231. Driving a real app end-to-end found four bugs that had passed 1,456 tests, all in parsing idb's
  232. output. The tests mocked a format idb never emits — newline-delimited objects with `label` fields —
  233. where idb really returns one JSON array using `AXLabel`. So `accessibility-quality-check` rated every
  234. screen unusable and `idb-ui-find-element` never matched anything, each while returning well-formed,
  235. plausible JSON. Fixtures now use captured idb output, and reintroducing one of those bugs fails ten
  236. tests.
  237. The same pass added crash reporting, element visibility and test-isolation tools, and removed the
  238. inert `defer_loading` flag.
  239. ### v5.0 · Simulator skill capabilities
  240. Adds semantic accessibility actions, diagnostic bundles, batch simulator filters, media import,
  241. container export, and hang-capture controls. The breaking change is explicit consent:
  242. `simctl-erase`, `simctl-delete`, `simctl-uninstall` and `idb-uninstall` require `confirm: true`.
  243. `workflow-fresh-install` retains its `eraseSimulator: true` opt-in. Use either a single `deviceId`
  244. or batch selectors (`all`, `deviceType`, `runtime`); combining an explicit ID with filters fails.
  245. Photo-library clearing also requires confirmation.
  246. ### The trade-off, version by version
  247. | Version | Tools | What set the context cost |
  248. |---|---|---|
  249. | v1.0 | 51 | Every description loaded at connect |
  250. | v1.3.2 | 51 | Descriptions trimmed; documentation moved behind `rtfm` |
  251. | v2.0 | 28 | Tool count cut by consolidating into routers |
  252. | v3.0 | 30 | A server-side deferral flag that never took effect |
  253. | v4.0 | 70 | Client-side deferral; routers dissolved for per-tool annotations |
  254. | v4.1 | 71 | Unchanged model; Xcode 27 support |
  255. | v4.2 | 77 | Unchanged model, verified against real idb output |
  256. | v5.1 | 81 | Duo pose controls and display-aware capture |
  257. | v5.0 | 80 | Semantic actions, diagnostic bundles and simulator skill capabilities |
  258. Two lessons carried forward. **Context cost is the client's call** — a server should describe its
  259. tools honestly and let the client decide how to spend context on them. And **a structured response
  260. can hide a broken tool** — test against the real command, not a mock of it.
  261. Release detail is in [CHANGELOG.md](./CHANGELOG.md).
  262. ### Migrating from v2/v3 routers
  263. Drop the `operation` field and call the matching tool. Operation-specific parameters are unchanged.
  264. | Removed router | Replacement tools |
  265. |---|---|
  266. | `simctl-device` | `simctl-boot`, `-shutdown`, `-create`, `-delete`, `-erase`, `-clone`, `-rename`, `-duo` |
  267. | `simctl-app` | `simctl-install`, `-uninstall`, `-launch`, `-terminate` |
  268. | `idb-app` | `idb-install`, `-uninstall`, `-launch`, `-terminate` |
  269. | `cache` | `cache-get-stats`, `-get-config`, `-set-config`, `-clear` |
  270. | `persistence` | `persistence-enable`, `-disable`, `-status` |
  271. `idb-targets` keeps its `operation` enum. `rtfm({ toolName: "simctl-device" })` still suggests the
  272. replacements.
  273. ---
  274. ## Development
  275. ```bash
  276. git clone https://github.com/conorluddy/xc-mcp.git
  277. cd xc-mcp && npm install
  278. npm run build # compile to dist/
  279. npm test # jest
  280. npm run lint # eslint
  281. ```
  282. ### Install the current checkout locally
  283. Build and package the checkout, then install the exact tarball into the active Node.js prefix:
  284. ```bash
  285. npm run build
  286. npm pack --pack-destination /tmp
  287. npm install --global /tmp/xc-mcp-5.1.0.tgz
  288. ```
  289. Use `xc-mcp` as the MCP client's command (with `--mini` if desired). `npx -y xc-mcp` may resolve
  290. an npm release rather than this local build. After switching Node.js versions, check `command -v xc-mcp`
  291. because global installations belong to that Node.js prefix. The CLI speaks MCP over stdio;
  292. verify it with an MCP client using initialize, tools/list and tools/call.
  293. Point any MCP client at a local build with `node /path/to/xc-mcp/dist/index.js`. **A running server
  294. holds `dist/` in memory**, so restart the client session after rebuilding.
  295. [AGENTS.md](./AGENTS.md) supplies contributor guidance; [CLAUDE.md](./CLAUDE.md) covers the architecture, how to add a tool, and the rules learned the hard
  296. way.
  297. ## Contributing
  298. > [!WARNING]
  299. > Contributions are welcome but reviewed slowly — this repo sits well down my priority list. Forking
  300. > and adapting it is usually the faster route.
  301. Pull requests need a passing build, tests and lint.
  302. ## License
  303. MIT, as declared in [`package.json`](./package.json).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.