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