@asagakosho/serve-sim-mcp

MCP server that exposes serve-sim as agent-callable tools, so LLMs (Claude Code, Claude Desktop, Cursor, etc.) can drive an iOS Simulator with structured tool calls instead of free-form shell commands.

Not affiliated with the upstream — this is a thin wrapper that shells out to the serve-sim CLI and xcrun simctl.

Why

• LLMs are bad at writing gesture JSON by hand. This package exposes high-level intents (sim_tap, sim_swipe, sim_button) so the agent never sees raw protocol details.
• Screenshots come back inline as image content, making the screenshot → reason → act loop trivial.
• Multi-device handling is uniform: every tool takes an optional udid.

Install / run

Requires macOS with Xcode command-line tools (xcrun simctl) and Node.js 18+. serve-sim itself is pulled in as a dependency — no separate install needed.

Claude Code / Claude Desktop / Cursor

Drop this into your client's MCP config (.mcp.json for Claude Code):

{
  "mcpServers": {
    "serve-sim": {
      "command": "npx",
      "args": ["-y", "@asagakosho/serve-sim-mcp"]
    }
  }
}

That's it — first run downloads the package, subsequent runs are cached. Restart the client so it picks up the new server.

Manual / global install

npm install -g @asagakosho/serve-sim-mcp
serve-sim-mcp   # speaks MCP over stdio

Tools (38)

Input

| Tool | What it does | | --- | --- | | sim_tap | Tap at normalized (0..1) coords | | sim_swipe | Swipe between two normalized coords | | sim_long_press | Press and hold at a coord for N ms | | sim_pinch | (stub — multi-touch CLI not yet exposed upstream) | | sim_gesture | Raw gesture event passthrough | | sim_button | home / lock / side-button / siri / apple-pay / volume-up / volume-down | | sim_rotate | portrait / portrait_upside_down / landscape_left / landscape_right | | sim_type_text | Type text via osascript (Simulator must be focused; ASCII-friendly) | | sim_open_url | Open URL or deep link |

Screen / device

| Tool | What it does | | --- | --- | | sim_screenshot | PNG inline as MCP image content | | sim_list_devices | Booted simulators (UDID, name, runtime) | | sim_boot | Boot by UDID or name | | sim_shutdown | Shut down one or all | | sim_erase | DESTRUCTIVE factory reset | | sim_status_bar | Override time / battery / wifi / cellular for clean screenshots | | sim_status_bar_clear | Remove overrides | | sim_memory_warning | Simulate low memory | | sim_ca_debug | CoreAnimation overlay (blended / copies / misaligned / offscreen / slow-animations) |

Apps / logs

| Tool | What it does | | --- | --- | | sim_app_launch | Launch by bundle id with optional args | | sim_app_terminate | Kill by bundle id | | sim_app_install | Install a .app bundle | | sim_app_uninstall | Uninstall by bundle id | | sim_app_container | Resolve app/data/groups container path | | sim_log_stream | Capture log stream for a bounded duration (default 5s) |

Privacy / push / media

| Tool | What it does | | --- | --- | | sim_grant_permission | Grant camera / photos / location / etc. without dialog | | sim_reset_permission | Reset so the dialog shows again | | sim_push | Deliver an APNs payload via simctl push | | sim_add_media | Add photos / videos to the Photos library |

Camera injection (wraps serve-sim camera)

| Tool | What it does | | --- | --- | | sim_camera_inject | Inject placeholder / file / webcam and (re)launch the app | | sim_camera_switch | Hot-swap source (no relaunch) | | sim_camera_mirror | auto / on / off | | sim_camera_status | JSON state of the helper | | sim_camera_list_webcams | Host cameras | | sim_camera_stop | Stop the helper |

Helper lifecycle

| Tool | What it does | | --- | --- | | sim_serve_start | serve-sim --detach (operation tools auto-start if needed) | | sim_serve_stop | serve-sim --kill | | sim_serve_status | { running: bool } | | sim_list_streams | Raw serve-sim --list output |

All tools accept an optional udid — omit when only one simulator is booted.

Recommended agent loop

1. sim_list_devices once at start (or rely on auto-detect with a single booted device).
2. sim_screenshot to see current state.
3. Decide next action; call sim_tap / sim_swipe / sim_open_url.
4. Wait a moment (animations), then go back to step 2.

Env

| Var | Default | Purpose | | --- | --- | --- | | SERVE_SIM_BIN | serve-sim | Override path to the serve-sim binary (e.g. when using a local checkout) |

License

Apache-2.0