# ios-sim-mcp [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/rmathew1973/ios-sim-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 78  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ios-sim-mcp

## Description
Drive the iOS Simulator via semantic accessibility-tree snapshots. Sub-200ms, no WebDriverAgent.

## Tools
Capabilities this server exposes over MCP:

- **list_simulators** — List simulators with UDID, state, OS version
- **use_simulator** — Pick a specific UDID (auto-selected if only one is booted)
- **snapshot** — Capture the AX tree, assign refs `e1..eN`, return compact text rendering. Filters: `interactive` (default), `actionable`, `all
- **find** — Search the snapshot by `id` (AXUniqueId), `label`, `labelContains`, `role`, `actionable
- **tap** — Tap by `{ref}`, `{id}`, or `{x,y}`. Optional `duration` makes it a long-press
- **type_text** — Type into the focused field. Optional `{ref}` or `{id}` taps-then-types. Auto-routes through paste when the dylib is loaded for byte-perfect input — no iOS autocorrect, no first-letter capitalization. `via: "keystroke"` forces the typing path; `via: "paste"` forces the paste path
- **paste_text** — Byte-perfect text via `UIPasteboard` + first-responder `paste:`. Requires the dylib injected. The right answer for emails, passwords, OAuth tokens, anything case-sensitive
- **view_tree** — Walk the running app's `UIView` hierarchy on the main thread. Reports class names, frames in window coords, alpha/hidden/interactive, text content, and annotates view-controller boundaries. Strictly richer than `snapshot` — sees custom-drawn views, transient overlays, SwiftUI internals. Filter by `…
- **view_hit_test** — "What view actually receives a tap at (x,y)?" Returns the topmost view plus the full responder chain up to `UIApplication`. The right debugging tool when a `tap` isn't doing what you expect. Requires dylib injected
- **network_start** — Install/remove an `URLProtocol` interceptor + swizzle `URLSessionConfiguration` so every `URLSession`-based HTTP request flowing through the app is recorded. Options: `max_records`, `max_body_bytes`, `filter_url_substring`. Requires dylib injected
- **network_tail** — Return the most recent N captured records. Default: one line per request (id, method, status, timing, sizes, URL). `full=true` includes headers + body previews inline. Page forward via `since_id
- **network_get_body** — Fetch the full request or response body (up to `max_body_bytes`, default 256KB) for a specific record id. Returns base64 + UTF-8 decode for text bodies
- **network_clear** — Drop the ring buffer and all retained bodies
- **network_self_test** — Fire an HTTP request from inside the app to verify the capture path end-to-end
- **network_stub** — Register canned HTTP responses by URL substring (+ optional method). Synthesizes status/headers/body without forwarding; `delay_ms` simulates slow networks. Stubbed requests still appear in `network_tail` with `stubbed:true
- **eval_js** — Run arbitrary JavaScript in a persistent `JSContext` inside the injected app. Bridged globals: `app`, `key_window()`, `all_windows()`, `defaults`, `pasteboard`, `bundle`, `process`, `notif_center`, `first_responder()`, `find_view_by_ax_id`, `find_view_by_class`, `find_vc_by_class`, `post_notificati…
- **eval_js_reset** — Drop the JSContext and rebuild bridges on next eval — forgets your defined vars/fns
- **key** — Press a key by name (RETURN, ESC, DELETE, TAB, SPACE, F1–F12, arrows) or raw HID code
- **button** — Hardware button: HOME, LOCK, SIDE_BUTTON, SIRI, APPLE_PAY
- **swipe** — Swipe between two refs/ids/points. Optional `duration` and `delta
- **scroll** — Reader-perspective scroll: `down` reveals content below. Optional anchor element
- **launch_app** — Launch by bundle id. Optional `foreground_if_running` terminates first
- **terminate_app** — Terminate by bundle id
- **screenshot** — PNG to disk or inline. Use sparingly — the AX tree is faster and richer
- **await_quiescent** — Block until the AX-tree hash is identical for `stable_ms` (default 250) or `timeout_ms` (default 5000). Use after launches and navigation instead of sleep
- **log_start** — Stream `os_log` into a 5000-line ring buffer. Filter by `bundle_id` substring, `level`, or NSPredicate

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What ios-sim-mcp MCP server does

ios-sim-mcp MCP server connects an MCP client to a booted iOS Simulator and exposes tools for selecting devices, reading accessibility data, interacting with applications, and inspecting runtime behavior. Its primary interaction model is a compact accessibility-tree snapshot: elements receive references such as `e1` through `eN`, which can then be used for taps, typing, swipes, and scrolling.

The server also includes lower-level capabilities for injected applications. These include walking the UIKit view hierarchy, identifying the responder chain for a screen coordinate, recording and stubbing URLSession traffic, evaluating JavaScript in a persistent JSContext, and streaming system logs.

## How it works

The simulator-facing layer uses Facebook's `idb` bridge to communicate with CoreSimulator. Tools such as `snapshot`, `find`, `tap`, `type_text`, `swipe`, `scroll`, `launch_app`, and `screenshot` operate through that layer. `await_quiescent` can wait for the accessibility-tree hash to remain unchanged instead of requiring a fixed sleep.

Optional in-process features are provided through a dylib loaded into the target app. That path communicates over a Unix socket using JSON Lines and runs view inspection, network interception, JavaScript, and related operations inside the application process. The dylib is required by tools such as `paste_text`, `view_tree`, `view_hit_test`, the network tools, and `eval_js`.

## Setup and configuration

The required environment is macOS with Xcode and iOS Simulator, `idb`, Bun, and a booted simulator. Install `idb-companion` and `fb-idb` using the commands documented by the project, then boot a device with `xcrun simctl boot <udid>` or through Xcode.

The quickest installation uses `npx -y ios-sim-mcp`. Source installations use `bun install` and can build the optional dylib with `./dylib/build.sh`. MCP clients should use an absolute Bun path when the client starts processes with a restricted `PATH`.

ios-sim-mcp MCP server uses standard stdio transport. Claude Code and Claude Desktop configuration examples are provided, and other MCP clients can run `bun run src/server.ts` and communicate using JSON-RPC.

## Tools and capabilities

- List simulators, select a UDID, and launch or terminate apps by bundle ID.
- Capture and search accessibility snapshots by identifier, label, role, or actionability.
- Tap, long-press, type, paste, press keys, use hardware buttons, swipe, and scroll.
- Inspect UIKit views, hit-testing results, custom-drawn content, overlays, and view-controller boundaries.
- Capture, inspect, clear, and stub URLSession requests, including request and response bodies.
- Run persistent JavaScript against bridged app objects and reset the JavaScript context.
- Stream filtered `os_log` output into a bounded ring buffer.

## Limitations and notes

A simulator must be available and booted before device operations can run. Screenshot capture is available, but the project positions accessibility snapshots as the faster primary representation. Injected features require the dylib to be loaded into the target application; building it is only necessary when using source installation with injection. Network interception covers URLSession-based HTTP traffic, not an unrestricted system-wide traffic proxy.

_Full upstream README: https://allmcps.com/mcp/ios-sim-mcp/readme_