ios-sim-mcp

An MCP server that drives the iOS Simulator the way Chrome's DevTools MCP drives a browser: semantic accessibility-tree snapshots with stable element refs, sub-200ms operations, and no screenshot-and-eyeball-coordinates loops.

Built because every existing iOS-simulator automation tool either crawls (Appium, screenshot-based agents) or requires pre-written scripts. This one lets an LLM drive a simulator interactively — find an element by label or ID, tap it by ref, wait for the UI to settle, repeat — at roughly the speed a human would.

Why this exists

Most existing iOS-sim MCPs work by taking a screenshot, asking the model to identify coordinates, then tapping pixels. That's slow (image bytes in context), expensive (vision tokens), and fragile (any layout shift breaks it).

iOS apps already expose a structured accessibility tree — the same one VoiceOver uses. If you query that tree, you get every interactive element with its label, role, AX identifier, frame, and enabled state. You can find what you want semantically, refer to it by a stable ref, and act on it directly. That's what Chrome MCP does for the DOM, and it's what this does for UIView hierarchies in the iOS Simulator.

How it works

Three layers, two shipping today:

idb talks directly to CoreSimulator's private framework — no WebDriverAgent, no HTTP hop into the simulator process — which is why the per-call latency is closer to a local subprocess than to a network round trip.

Requirements

• macOS with Xcode + iOS Simulator
• idb (brew tap facebook/fb && brew install idb-companion && pipx install fb-idb)
• Bun (curl -fsSL https://bun.sh/install | bash)
• A booted simulator (xcrun simctl boot <udid> or open it in Xcode)

Install

Quickest path (npm + npx)

# Register with Claude Code, one line:
claude mcp add -s user ios-sim -- npx -y ios-sim-mcp

npx will fetch the package on first run. Verify:

claude mcp list | grep ios-sim     # ios-sim: ... ✓ Connected

Layer 2 dylib ships prebuilt as a universal binary (arm64 + x86_64) — works on both Apple Silicon and Intel Macs out of the box.

From source

git clone https://github.com/rmathew1973/ios-sim-mcp.git
cd ios-sim-mcp
bun install
./dylib/build.sh         # builds the Layer 2 dylib (only needed if you'll use inject:true)

Then register:

# Prefer the absolute bun path — clients with a minimal PATH fail on bare `bun`:
claude mcp add -s user ios-sim -- "$HOME/.bun/bin/bun" run "$(pwd)/src/server.ts"

Register with Grok (CLI / Desktop)

Grok MCP spawn PATH is often just /usr/bin:/bin. Bare bun fails with:

Failed to spawn MCP server 'ios-sim': No such file or directory (os error 2)

Use the absolute bun binary in ~/.grok/config.toml:

[mcp_servers.ios-sim]
command = "/Users/YOU/.bun/bin/bun"
args = ["run", "/Users/YOU/Projects/ios-sim-mcp/src/server.ts"]
enabled = true
startup_timeout_sec = 60

Or:

grok mcp add ios-sim -- "$HOME/.bun/bin/bun" run "$HOME/Projects/ios-sim-mcp/src/server.ts"

Restart the Grok session after changing MCP config. Verify: grok mcp list should show ios-sim connected (not failed).

Register with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Or, if installed from source, point at the local path:

{
  "mcpServers": {
    "ios-sim": {
      "command": "/Users/YOU/.bun/bin/bun",
      "args": ["run", "/absolute/path/to/ios-sim-mcp/src/server.ts"]
    }
  }
}

Quit and reopen Claude Desktop.

Register with anything else (generic MCP client)

It's a standard stdio MCP server. Run bun run src/server.ts and pipe JSON-RPC. See test/smoke.ts for a working client example.

Tools

Example session

> snapshot
# Settings  screen=402x874  v=5  elements=15
  e3 Button "Apple Account" #com.apple.settings.primaryAppleAccount @(201,213)
  e5 Button "General" #com.apple.settings.general @(201,406)
  e6 Button "Accessibility" #com.apple.settings.accessibility @(201,458)
  e14 TextField "Search" ="Search" @(201,822)
  ...

> tap {id: "com.apple.settings.general"}
tapped e5/com.apple.settings.general

> await_quiescent {stable_ms: 250}
stable hash=8326196f25c8 samples=4 elapsed=1731ms

> snapshot
# Settings  v=10  elements=13
  e2 Button "Settings" #BackButton @(38,84)
  e6 Button "About" #About @(201,418)
  ...

> type_text {ref: "e14", text: "wifi"}
typed 4 chars into e14

Measured on iPhone 17 Pro / iOS 26.5 / M-series Mac:

• snapshot: 127–190 ms
• tap: 100 ms
• find: <1 ms (in-memory against cached snapshot)
• await_quiescent: 400 ms – 2.5 s (real UI settle time)

Design notes

• Snapshots are versioned and cached. Any action (tap, swipe, type_text, launch_app, button, key) invalidates the cache so stale refs can't survive a state change. find and ref resolution will tell you to re-snapshot rather than acting on old data.
• Refs are stable within a snapshot, not across snapshots. e5 in v=10 is not the same element as e5 in v=11. AXUniqueIds (the iOS accessibilityIdentifier) are stable across snapshots and are the preferred way to target a control across UI changes.
• await_quiescent ignores degenerate AX trees. For ~1s after launch_app, idb returns just the AXApplication root with no children. A naive hash-stability check would return instantly with an empty tree. The implementation resets the stability timer whenever it sees a degenerate snapshot.
• scroll is reader-perspective. down means "see what's below" (finger drags up), matching mouse-wheel/page-down conventions, not finger-direction. Default 0.4s gesture duration prevents iOS from interpreting the release point as a tap on the underlying element.

Tip: add accessibility identifiers to your own apps

This MCP is fastest and most reliable when interactive controls have accessibilityIdentifier set:

Button("Sign In") { ... }
  .accessibilityIdentifier("login_submit_button")

Then tap({id: "login_submit_button"}) is O(1) and survives label changes, localization, and layout shifts.

Layer 2 dylib (optional, opt-in per launch)

launch_app({bundle_id, inject: true}) loads a small dylib into the target app via SIMCTL_CHILD_DYLD_INSERT_LIBRARIES. The dylib opens a Unix socket at /tmp/ios-sim-mcp-<bundle-id>.sock and serves JSON-Lines RPC. You can then talk into the running app:

dylib_ping({ echo: "hi" })          // pong from com.apple.Preferences (RTT 1ms)
dylib_info({})                       // {pid, bundle_id, process_name, bundle_path, methods, ...}
dylib_call({ method: "...", params }) // generic; future phases register more methods

Once connected, IPC is sub-millisecond per call — orders of magnitude cheaper than Layer 1's subprocess-spawn overhead. Connection is lazy (first dylib_* call) and pooled per bundle id; relaunch invalidates the old client automatically.

Why you want to launch with inject: true even for casual driving

iOS auto-capitalizes the first letter of typed input, swaps " ' for smart-quotes, and runs autocorrect on anything that looks like a word. For driving UI those transformations silently mangle:

• qa-consumer2@geoland.test becomes Qa-consumer2@geoland.test → server rejects the email → login fails with no obvious cause
• café becomes nothing iOS can even render → field receives garbage
• a"b'c becomes A after smart-quote substitution and autocorrect

With the dylib loaded, type_text auto-routes through UIPasteboard.general.string = text + the first responder's paste:. Bypasses the keyboard entirely. Whatever you pass arrives byte-perfect.

Build it once:

./dylib/build.sh         # outputs dylib/build/libios-sim-mcp.dylib

The dylib is iOS-Simulator-flavored (LC_BUILD_VERSION platform 7, iOS 14+), only loads in apps you launch through this tool with inject: true, does not modify the app on disk, and leaves no trace after the process exits.

When to use snapshot vs view_tree

Both inspect the running UI but they read different trees:

Rule of thumb: use snapshot + find for "tap this control" workflows (especially in SwiftUI apps); use view_tree for "what's actually on screen and why isn't this working" investigation.

Network capture (Layer 2d)

launch_app({ bundle_id: "com.yourco.app", inject: true })
network_start({ max_body_bytes: 262144 })
// ... use the app normally ...
network_tail({ n: 20, full: true })
// → #34 POST 201 142ms ttfb=98ms reqB=312B resB=2.3KB application/json  https://api.yourco.com/orders
//     request_headers:
//       Authorization: Bearer eyJhbG...
//       Content-Type: application/json
//     request_body:
//       {"sku":"PRO_MONTHLY","quantity":1,"coupon":"WELCOME10"}
//     response_body:
//       {"order_id":"ord_8a3f2c","total":2700,...}
network_get_body({ id: 34, which: "response" })  // full body if it was truncated

Scope:

• ✅ Catches all URLSession-based traffic: native URLSession, URLRequest, Alamofire, SwiftUI AsyncImage, anything that consumes URLSessionConfiguration.default or .ephemeral
• ✅ Decrypted HTTP/HTTPS bodies — we sit inside the URLSession pipeline above TLS
• ✅ No certificate install, no mitmproxy, no proxy config
• ⚠️ Does NOT catch: raw CFNetwork / nw_connection_t (low-level networking written against the BSD socket layer), background URLSessions, gRPC libraries that bypass URLSession, WKWebView resource loads (separate process)
• ⚠️ HTTPBodyStream request bodies are noted but not captured (would require draining + rewinding the stream)
• ⚠️ Sessions constructed before network_start are not retro-fitted; restart the app or relaunch with inject:true if you need to catch app-startup traffic

Network stubbing (Layer 2f)

Register canned responses for any URL substring; the dylib synthesizes the response instead of forwarding. Unlocks deterministic error-path and slow-network testing without touching the backend.

// Force a 401 for the next login attempt
network_stub({
  url_substring: "/api/auth/login",
  method: "POST",
  status: 401,
  headers: { "Content-Type": "application/json" },
  body: '{"error":"invalid_credentials"}',
})

// Simulate slow API for offline-UX testing — 3 second delay
network_stub({
  url_substring: "/api/products",
  delay_ms: 3000,
  status: 200,
  body: '[{"sku":"FAKE","name":"Stub Product"}]',
})

// Now drive the app — login fails as if password was wrong; product list spinner shows
network_stubs()       // list active stubs
network_unstub({id})  // remove one
network_unstub_all()  // clear them all

Stubbed requests still appear in network_tail with stubbed:true and the matching stub_id, so you can verify the app sent what you expected before the synthesized response.

Scripting the running app (Layer 2e)

launch_app({ bundle_id: "com.yourco.app", inject: true })

eval_js({ code: "bundle.bundleIdentifier" })
// → "com.yourco.app"

eval_js({ code: "app.windows[0].rootViewController.title || 'untitled'" })
// → "Home"

// Toggle a feature flag stored in NSUserDefaults
eval_js({ code: "defaults.setBoolForKey(true, 'feature.dark_mode'); 'set'" })

// Inspect or mutate a live view
eval_js({ code: "var v = find_view_by_class('UITextField'); v && (v.text = 'qa@example.com')" })

// Define a helper, use it later — state persists across calls
eval_js({ code: "function visibleWindows(){return all_windows().filter(w => !w.isHidden && w.alpha > 0.01);}" })
eval_js({ code: "visibleWindows().length" })
// → 1

Bridged globals (all installed automatically on first eval_js):

JSC's JSExport is implemented on UIView, UIWindow, UIViewController, UILabel, UIButton, UITextField, UITextView, UIApplication, NSBundle, NSProcessInfo, NSUserDefaults, UIPasteboard so common property access and method calls work without further bridging. Selector colons become camelCase function names: setObject:forKey: → setObjectForKey(value, key).

App extensions, helpers, plugin hosts

SIMCTL_CHILD_DYLD_INSERT_LIBRARIES only affects the process simctl directly launches — not SpringBoard, not Mediaserverd, not other system daemons. Within your app's own sub-processes (XPC helpers, app extensions launched on demand: share, action, today widget), the dylib will load if dyld honors the env var. To keep things sane:

• If a loaded process has [NSBundle mainBundle].bundleIdentifier empty or nil (XPC helpers, certain plugin hosts), the dylib silently skips socket binding — no MCP exposure, no /tmp/ios-sim-mcp-*.sock path collision with the main app.
• If a loaded process is a real app extension with its own bundle id (e.g. com.yourco.app.ShareExtension), the dylib opens a distinct socket at /tmp/ios-sim-mcp-<extension-bundle-id>.sock. You can drive the extension independently by passing that bundle id to dylib_* tools.
• In normal flows you only launch_app your main app. Extensions launched by iOS during a share/widget interaction are technically reachable but not normally targeted — set bundle_id explicitly on every tool call when you want one.

Distribution model — why runtime injection, not SwiftPM

We ship Option 1: prebuilt universal dylib, injected at runtime via DYLD_INSERT_LIBRARIES. Devs add nothing to their Xcode project — no SPM dep, no build setting, no #if DEBUG guard. The dylib physically isn't part of their app, so App Store submission and production builds are unaffected.

The alternatives we considered:

Option 1 covers the 90% case (driving any iOS sim with no project changes), so we shipped it first. Option 2/3 are reasonable future additions if a user team specifically wants to introspect their own Swift internals.

Safety & production posture

The Layer 2 dylib is engineered to never crash the host app:

• SIGPIPE is ignored globally and SO_NOSIGPIPE set per-fd, so a closed MCP-side socket cannot kill the host process.
• Every dispatched task (accept loop, per-connection serve, URLSession delegate callbacks, stub synthesis, view walks, JS eval) is wrapped in @try and logs via os_log on catch rather than propagating.
• The accept loop survives transient accept() failures with a 250ms backoff instead of exiting.
• Method handlers run on a background queue; UIKit-touching ones bounce to main via dispatch_sync with caller-controllable timeouts.
• Buffers are bounded: 5,000 log lines, 500 network records (configurable), 256KB body cap (configurable).
• All shared state is NSLock-protected.

This is a dev/test tool, not for production builds. Two safety invariants make it appropriate only for engineering simulators:

1. No App Store risk — DYLD_INSERT_LIBRARIES is a runtime injection via SIMCTL_CHILD_* env vars. The dylib is never linked, embedded, or shipped with your app binary. App Store builds physically cannot load it.
2. Opt-in per launch — launch_app defaults to inject: false. The dylib only loads when you explicitly pass inject: true, and only in the simulator (Apple's hardened-runtime + code-signing requirements prevent DYLD injection into real-device or production builds).

If you accidentally call a dylib-only tool (view_tree, eval_js, network_*, etc.) without inject: true, you get an actionable error pointing at the fix — never a hang or a crash. Use dylib_health for non-throwing feature detection in scripts.

Roadmap

• describe_point — "what's under (x,y)?" for debugging gesture targets.
• Video recording — wrap idb record-video as record_start/record_stop.
• Multi-sim parallelism — share one server across multiple booted devices for matrix testing.
• JS interactive REPL tool — multi-line buffer with history, useful for ad-hoc exploration.

License

MIT.