Skip to main content
Glama

ios-safari-mcp

An MCP server that drives iOS 16.5 Safari running in QEMU on the HackiOS kernel, so that an agent (or a test) can look at a real iOS WebKit page, read its DOM, run JavaScript in it, watch its console and network, and work with the software keyboard the way iOS does it.

It is a companion to the HackiOS repositories (the kernel and the userland that boot unmodified iOS in QEMU). It adds no Apple code and changes none of the parent's source by hand: it patches a few lines of the parent's build at build time (scripts/apply-to-tree.py) and ships one small guest program, the relay.

See

screenshot (0.22 s), settle (wait for the screen to stop changing)

Touch

tap, swipe, scroll, key, tap_element (a real tap at a CSS selector's measured position)

Read and run

js, dom, console_messages, network_log, inspector_raw (any Web Inspector command)

Navigate

open_url, navigate, reload, safari_ready (no typing, no tap)

Keyboard

keyboard_state, keyboard_show, keyboard_hide, keyboard_events, keyboard_check, fill, type_text

VM

vm_start (boot or restore), vm_stop, vm_save, vm_snapshots, vm_status, wait_for, guest_process, log_tail

41 tools in all; tools/list has the full schemas. No runtime dependencies beyond Python 3 and Nix.

Status

Read this before relying on it. "Verified live" means: run against the real guest, 24 October 2026, on one machine.

Verified live

on a fresh boot of an image built by ios-safari-mcp build-image, through one long-lived MCP session (tests/live/smoke.py, 13 steps, all passed, again after the review fixes): safari_ready (SpringBoard opened example.com, no tap, no typing), inspector_pages, js, dom, navigate, open_url, network_log, console_messages, screenshot, keyboard_state, keyboard_check; also keyboard_show and keyboard_hide (blur and done); vm_save, and a restore from that snapshot with the inspector working afterwards (see Known problems)

Verified offline

59 tests (nix flake check; the earlier commits are green on GitHub Actions): the property list format against 24 frames captured from Safari, the client and every tool against a fake relay, calibration, the keyboard tools, the JSON-RPC surface, lint

Not verified live

keyboard_events, tap_element, tap_css, scroll_into_view, keyboard_hide by return and tap_outside; type_text on any keyboard but Safari's address bar; the relay replacing a client that is still connected; Safari on other iOS versions or other screen sizes (all runs: iPhone X, 375 x 812 points)

Related MCP server: @mgcrea/mcp-ios-simulator

Quick start

You need Linux, Nix with flakes, 12 GB of RAM and 10 GB of disk. The VM boots in 7 to 14 minutes (software emulation, no KVM on an x86 host); a restored snapshot takes about 30 seconds.

  1. Get the parent and the iOS files. Check out the HackiOS kernel and userland repositories into one tree as their README says, then fetch iOS 16.5 (about 6 GB, from Apple's servers): cd ios165 && ./fetch.sh. The parent has fixes that were still open pull requests when this was written (the black screen, the missing on-demand jobs, the /bin/bash shebangs on NixOS, the 7-Zip version): docs/findings.md lists them; without the first two the screen stays black and there is no network.

  2. Check the setup. nix run github:meros/ios-safari-mcp -- doctor lists what is missing, with the command that fixes each item. Set HACKIOS_DIR to the tree (the default is ../hackios next to a checkout, then ~/hackios).

  3. Build the image. nix run github:meros/ios-safari-mcp -- build-image builds the relay, patches the parent's build and builds the image. It takes a few minutes and needs the iOS files.

  4. Register the server.

    claude mcp add ios-safari -e HACKIOS_DIR=$HOME/hackios -- nix run github:meros/ios-safari-mcp --

    or in any MCP client's config:

    { "mcpServers": { "ios-safari": { "command": "nix", "args": ["run", "github:meros/ios-safari-mcp", "--"],
                                      "env": { "HACKIOS_DIR": "/home/you/hackios" } } } }

    From a checkout, use bin/ios-safari-mcp as the command (no install).

  5. Use it. vm_start, wait_for springboard_owns_screen, safari_ready with a url, then the tools below. Save a snapshot once Safari is up (vm_save safari-ready) and every later session starts with vm_start snapshot=safari-ready.

A session

vm_start                         -> boots (minutes)           | or: vm_start snapshot=safari-ready (30 s)
wait_for springboard_owns_screen
safari_ready url=https://example.com
js  expression="document.title"  -> "Example Domain"
dom selector=".CookieConsent button" what=text
tap_element selector=".CookieConsent-button.nb-button--blue"
keyboard_check selector="input[placeholder^='Område']" value="Bullerbygatan"
                                 -> verdict, what the keyboard covers, a screenshot with it up, viewport recovery

The keyboard

On iOS Safari the keyboard does not resize the page: window.innerHeight stays, visualViewport.height shrinks, position: fixed elements stay put and can end up behind the keyboard, and script cannot open the keyboard (focus() outside a user gesture focuses the field without it). So the tools work with a real touch:

  • keyboard_state returns both viewports, the keyboard height in CSS px, the focused field and whether it is visible above the keyboard, interactive elements and popups that reach under it, and fixed or sticky bars (behindKeyboard).

  • keyboard_show selector=... scrolls the field into view, finds it on the screen, taps it and waits for the viewport to shrink. tap_element and tap_css use the same measured mapping from page to screen pixels (a 14 px marker drawn in the page and found in a screenshot, cached until the layout changes).

  • keyboard_hide closes it by blur (default), the return key, or a tap outside, and waits for the viewport to recover.

  • keyboard_events records focus, key, composition and viewport events with the viewport numbers at each moment.

  • keyboard_check does all of it for one field and reports ok or problems: the field hidden, a fixed bar behind the keyboard, a suggestion popup reaching under it, a viewport that does not recover.

  • fill sets a value fast (native setter, input and change events); it is synthetic. type_text taps the on-screen keys (about 2.5 s a key) for real key events, autocorrect and composition. Key positions are verified for letters on Safari's address bar keyboard only; digits and symbols follow the standard layout and other keyboard types (email, number pad) are not mapped.

On the search field of a property marketplace (iPhone X size, 23 October 2026): the keyboard was 269 CSS px tall (viewport 635 → 366), the field stayed visible, and the viewport recovered after blur().

Measured

Intel Core Ultra 7 258V, on battery with turbo off. The guest draws in software, so it is slow by phone standards; the inspector is fast on an idle page. The guest is emulated on the host's cores: heavy work on the host during a run slows it 10 to 40 times. The second column was measured while the host also ran a test suite and a Nix build; the first with the host otherwise idle.

What

Idle host

Busy host

js 1 + 1 (through MCP)

0.2 s

2 to 16 s

dom, js of a page title

0.4 to 0.5 s

2 to 4 s

navigate to a page already loaded (inspector)

2.0 s

15 to 20 s, one run timed out

open_url of a page (warm)

3.2 s

20 s

safari_ready with a page open / Safari not running

4.5 s / 74 to 130 s

first HTTPS load of a site after boot (cold)

57 to 87 s

keyboard_check (open, type, report, screenshot, close)

15.6 s

81 s

keyboard open after a real tap / closed by blur() / by Done

4 to 7 s / 8 to 10 s / 2 s

up to 28 s

screenshot

0.1 to 0.2 s

a tap until the screen shows the result

14 to 60 s

boot to SpringBoard

7 to 14 min

vm_save (2.9 GB) / restore

112 s / 18 s

Known problems

Symptom

Cause and what to do

After a restore, the page that was open does not answer (js says "did not answer the setup")

A page that was open when a snapshot was restored is no longer inspectable; new pages are. open_url notices, asks SpringBoard to open the address and attaches to the new page (15 s).

Everything is slow or times out

Something else is using the host's cores. The guest is emulated in software on them; stop heavy work (builds, test suites) while the VM is in use.

Taps do nothing

In some boots backboardd does not accept the virtual touchscreen (a start-up race in the guest). vm_status shows touchscreen: not recognized. vm_stop and vm_start again. Seen once in about ten boots.

Pages fail with "network connection was lost" right after boot

The guest network needs a few minutes to warm up (the first DNS lookup took 26 s). Wait and retry.

inspector_pages is empty

Safari is not running, or shows its native start page (no web page exists). safari_ready or open_url opens one.

"the page did not answer the setup"

Another frontend is attached to the page. A page takes one at a time; the next call ends stale connections.

Ticket spinlock timeout panic

The host starved a vCPU thread. vm_start already raises the kernel's timeout (slto_us). Close other heavy work.

Everything is black

The display turned itself off: wake.

More, with the reasons: docs/findings.md.

How it works, in short

Safari does not offer its inspector to the outside. Its processes send inspector messages to a system service, webinspectord. This project replaces that service with a small program in the guest (guest/wi_relay.c, about 470 lines of C, built without the iOS SDK) which posts the notification apps wait for, accepts their connections, and passes their messages over TCP (a QEMU port forward) to this server, which speaks WebKit's inspector protocol. Details and the wire formats: docs/architecture.md. Development, tests and fixtures: docs/development.md.

Licence

MIT, see LICENSE. This repository contains no file of Apple's iOS and none of the HackiOS kernel or userland. The parent's kernel tree is under the Apple Public Source License 2.0, its userland tree under MIT. This is not an official part of HackiOS and not affiliated with Apple. The property list format of Safari's messages was worked out from captured traffic.

Available Tools

41 tools
backA

Back in Safari: taps the toolbar back arrow (the toolbar must be showing; scroll up a little or tap the bottom bar first). method=swipe uses the left-edge gesture, which did not navigate in testing.

Inputs: ms, method, settle, timeout, +2 more.

console_messagesC

Console messages of the page since the inspector attached (level, text, url).

Inputs: page, wait, clear, limit.

domB

Query the DOM by CSS selector. what=info (default: tag, text, attributes, rect in CSS px, visible), html (outerHTML) or text.

Inputs: page, wait, what, limit, +1 more.

fillA

Set the value of a field the way a framework notices (native setter, then input and change events). Fast, but synthetic: no key events, no keyboard, no autocorrect or composition. Use keyboard_show and type_text for those.

Inputs: value (required), selector (required), page, wait, +2 more.

guest_processB

Is a process running in the guest (by name, e.g. MobileSafari, wi_relay)? Returns pid and thread count.

Inputs: name (required), timeout.

holdC

Touch and hold.

Inputs: x (required), y (required), ms, settle, +3 more.

home_screenC

Leave the app: swipe up from the bottom edge.

Inputs: settle, timeout, stable_for, wait_change.

inspector_closeA

End the inspector connection (a page takes one frontend at a time). The next inspector call reconnects.

Inputs: no named parameters.

inspector_pagesB

List the pages that Safari offers to the Web Inspector (title, url). Safari must be running with a page open; safari_ready makes sure of that.

Inputs: all, wait.

inspector_rawC

Send any Web Inspector protocol command to the page (e.g. Page.getCookies, DOM.getDocument, Debugger.enable) and return the result.

Inputs: method (required), page, wait, params, +1 more.

jsC

Run a JavaScript expression in the page and return its value as JSON. Milliseconds, no screenshot or typing.

Inputs: expression (required), page, wait, await_promise.

keyC

Press a hardware button: lock, home, volup, voldown.

Inputs: name (required), ms, settle, timeout, +2 more.

keyboard_checkA

Open the keyboard on a field and report whether it covers anything important: the field itself, fixed bars, suggestion popups. Optionally puts a value in the field first, to bring up suggestions. Returns the report and a screenshot with the keyboard up, then closes the keyboard and checks that the viewport recovers.

Inputs: hide, page, wait, index, +3 more.

keyboard_eventsA

Record what the page sees around the keyboard: focusin/focusout, keydown/keyup, beforeinput/input, composition events and every window and visualViewport resize or scroll, each with the viewport numbers at that moment. action=start installs the recorder (a navigation removes it), read returns the events (since = how many to skip), stop removes it.

Inputs: action (required), page, wait, clear, +1 more.

keyboard_hideA

Close the keyboard and wait for the viewport to recover. method=blur (default) blurs the field, as a page does; done taps Safari's Done button above the keyboard (what a user presses); return taps the keyboard's bottom right key (it may submit a form); tap_outside taps a point of the page outside the field (x and y in CSS px; default the left edge).

Inputs: x, y, page, wait, +2 more.

keyboard_showA

Open the keyboard on a field with a real tap (script focus() does not open it on iOS): scrolls the field into view, finds where it is on the screen, taps it, and waits until the visual viewport has shrunk. Returns the state with the keyboard up.

Inputs: selector (required), page, wait, index, +2 more.

keyboard_stateA

Is the keyboard up, how tall is it, and what does it cover? Returns the layout and visual viewport, the focused field and whether it is visible above the keyboard, the interactive elements and popups that reach under the keyboard, and the fixed or sticky elements (with behindKeyboard set when a bar is hidden by it). Heights are CSS px.

Inputs: page, wait.

log_tailC

Last lines of the guest console log, optionally filtered by a regex.

Inputs: lines, pattern.

network_logC

Requests of the page since the inspector attached: url, method, status, mime type, failures.

Inputs: page, wait, limit.

open_urlA

Open an address in Safari: through the inspector when a page exists (about 3 s), else by asking SpringBoard (starts Safari too). No typing. typing=true types it on the keyboard instead (minutes).

Inputs: url (required), page, typing, delay_s, +1 more.

reloadC

Reload the page.

Inputs: page, wait, ignore_cache.

safari_readyB

Get Safari running with a page the inspector lists, without a tap or typing: asks SpringBoard to open url (default about:blank), which starts Safari. Call this after the VM has booted or a snapshot is restored.

Inputs: url, timeout.

screenshotA

PNG of the phone screen (1125x2436, scaled down by scale, default 2).

Inputs: scale.

scrollC

Scroll the page (direction up/down/left/right, amount as a fraction of the screen, default 0.4).

Inputs: amount, settle, timeout, direction, +2 more.

scroll_into_viewC

Scroll an element into view (block: start, center, end or nearest).

Inputs: selector (required), page, wait, block, +1 more.

settleA

Wait until the screen stops changing (two frames equal for stable_for seconds) or the timeout ends.

Inputs: timeout, stable_for.

swipeB

Swipe. Swipe up from y=0.985 to open or leave an app; from the left edge for back.

Inputs: x0 (required), x1 (required), y0 (required), y1 (required), +5 more.

tapA

Tap. x and y are fractions of the screen, 0,0 top left. For a page element use tap_element.

Inputs: x (required), y (required), settle, timeout, +2 more.

tap_cssB

Tap a point given in CSS pixels of the layout viewport (what getBoundingClientRect returns).

Inputs: x (required), y (required), page, wait.

tap_elementB

Tap the middle of a page element by CSS selector, with a real touch at the right screen position (measured, so it is right whatever Safari's bars and the keyboard are doing).

Inputs: selector (required), page, wait, index, +1 more.

tap_pxC

Tap a point given in pixels of a screenshot you took (set scale to the same value as the screenshot).

Inputs: x (required), y (required), scale, settle, +3 more.

type_textA

Type by tapping the keys of the on-screen keyboard, which must be showing: slow (about 2.5 s a key) but real key events. Lower-case letters, digits, space and . - / : ( ) ; $ & @ " are known; set submit to press go. For fast input use fill.

Inputs: text (required), settle, submit, delay_s, +3 more.

vm_saveA

Save the whole machine state to a named snapshot (takes a minute or more, files are GB). Restore with vm_start(snapshot=name). Only works for a VM started with saveable=true.

Inputs: name (required), resume, timeout.

vm_snapshotsB

List saved snapshots.

Inputs: no named parameters.

vm_startA

Boot HackiOS in QEMU in the background. Takes 9 to 14 minutes under software emulation; restoring a snapshot takes about 30 s. Then call safari_ready.

Inputs: cpus, seconds, saveable, snapshot, +1 more.

vm_statusB

Is QEMU running, did it panic, did the guest accept the touchscreen, and which boot phase was reached.

Inputs: no named parameters.

vm_stopB

Stop QEMU.

Inputs: no named parameters.

waitA

Sleep up to 60 s (the guest is slow; animations take time).

Inputs: seconds.

wait_forA

Block until a boot phase is reached (kernel, launchd, backboardd_ready, springboard_owns_screen, or running for a restored snapshot) or the timeout (max 280 s) ends.

Inputs: phase, timeout.

wakeC

Wake the display (it turns off after boot): a tap and then the home key.

Inputs: settle, timeout, stable_for, wait_change.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 41 tools

    Disambiguation3/5

    Several tools have overlapping boundaries: open_url and navigate are explicitly the same operation, and tap, tap_px, tap_css, and tap_element differ mainly by coordinate system, while fill versus keyboard_show/type_text represent competing input paths. Descriptions do a good job explaining when to use each variant, but the set still requires careful reading to avoid misselection.

    Naming Consistency4/5

    All names use a consistent snake_case convention with no camelCase mixing, and related tools are grouped by prefix (keyboard_*, vm_*, inspector_*). The only minor inconsistency is that some names are imperative verbs while others are nouns or bare operations (js, dom, screenshot, settle), but all remain readable and predictable.

    Tool Count2/5

    At 41 tools, the surface is very heavy for a single MCP server, even accounting for the complex VM, touch, inspector, and keyboard domains. Several tools could be collapsed or made modes of existing tools, such as open_url/navigate and the multiple tap and keyboard entry points.

    Completeness4/5

    Coverage is broad: VM lifecycle, touch input, text entry, navigation, Web Inspector access, console/network logs, keyboard diagnostics, screenshots, and settling. Minor gaps remain around app lifecycle beyond Safari, accessibility-tree-style element discovery, and other device interactions, but core Safari automation workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables programmatic control and AI-driven E2E testing of iOS virtual machines by exposing display, touch input, and navigation tools. It provides hardware key emulation, app navigation, and raw touch interactions with inline screenshot feedback for real-time visual context.
      17
      92
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables driving an iOS Simulator from a model: taking screenshots, reading the UI tree, tapping, swiping, typing, managing app lifecycle and device state such as appearance, permissions, location, and notifications, without code signing or a physical device.
      25
      89 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to check setup, manage iOS Simulator devices, build/install/launch iOS apps, capture screenshots, send input, and open a live browser preview. It connects local agent workflows to Apple's simulator without requiring a custom emulator or native pane.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables natural-language remote control and automation of iPads/iPhones over HTTPS, including app launching, accessibility inspection, taps, swipes, typing, device-local gesture sequences, and screenshot capture through a WebDriverAgent runner and cloud queue.
      MIT