Ios Sim MCP

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 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"})