ios-safari-mcp
This server lets you drive and inspect an emulated iOS 16.5 Safari running in QEMU on HackiOS, using real touch input, Web Inspector access, and keyboard testing.
Manage the VM: boot/restore, stop, save/list snapshots, check status, wait for boot phases, inspect guest processes and logs.
Control the screen and device: take screenshots, wait for UI settling, tap/hold/swipe/scroll, press hardware buttons, wake display, go home/back, and tap elements or coordinates.
Navigate Safari: open/navigate URLs, reload, ensure Safari is ready, list inspector pages, connect/close inspector sessions.
Work with web content: run JavaScript, query the DOM, read console messages and network requests, and send raw Web Inspector protocol commands.
Test the iOS software keyboard: inspect viewport/keyboard state, show/hide it by several methods, record keyboard events, check for overlap and recovery, fill fields, and type via on-screen keys.
Use page helpers: scroll elements into view, fill inputs synthetically, and tap CSS-layout positions.
Provides tools for driving an emulated iOS 16.5 device, including touch input, screenshots, software-keyboard inspection and control, and interaction with iOS Safari's viewport and keyboard behavior.
Provides tools for controlling Safari on iOS: open and navigate URLs, capture screenshots, tap elements, read the DOM, execute JavaScript, inspect console messages and network logs, and issue Safari Web Inspector commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ios-safari-mcp open example.com in Safari, then read the page title and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
Touch |
|
Read and run |
|
Navigate |
|
Keyboard |
|
VM |
|
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 |
Verified offline | 59 tests ( |
Not verified live |
|
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.
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/bashshebangs on NixOS, the 7-Zip version): docs/findings.md lists them; without the first two the screen stays black and there is no network.Check the setup.
nix run github:meros/ios-safari-mcp -- doctorlists what is missing, with the command that fixes each item. SetHACKIOS_DIRto the tree (the default is../hackiosnext to a checkout, then~/hackios).Build the image.
nix run github:meros/ios-safari-mcp -- build-imagebuilds the relay, patches the parent's build and builds the image. It takes a few minutes and needs the iOS files.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-mcpas the command (no install).Use it.
vm_start,wait_for springboard_owns_screen,safari_readywith aurl, then the tools below. Save a snapshot once Safari is up (vm_save safari-ready) and every later session starts withvm_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 recoveryThe 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_statereturns 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_elementandtap_cssuse 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_hidecloses it byblur(default), the return key, or a tap outside, and waits for the viewport to recover.keyboard_eventsrecords focus, key, composition and viewport events with the viewport numbers at each moment.keyboard_checkdoes all of it for one field and reportsokorproblems: the field hidden, a fixed bar behind the keyboard, a suggestion popup reaching under it, a viewport that does not recover.fillsets a value fast (native setter,inputandchangeevents); it is synthetic.type_texttaps 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 |
| 0.2 s | 2 to 16 s |
| 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 |
| 3.2 s | 20 s |
| 4.5 s / 74 to 130 s | |
first HTTPS load of a site after boot (cold) | 57 to 87 s | |
| 15.6 s | 81 s |
keyboard open after a real tap / closed by | 4 to 7 s / 8 to 10 s / 2 s | up to 28 s |
| 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 | |
| 112 s / 18 s |
Known problems
Symptom | Cause and what to do |
After a restore, the page that was open does not answer ( | A page that was open when a snapshot was restored is no longer inspectable; new pages are. |
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 |
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. |
| Safari is not running, or shows its native start page (no web page exists). |
"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. |
| The host starved a vCPU thread. |
Everything is black | The display turned itself off: |
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 toolsbackA
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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Build, run, and inspect iOS apps in disposable hosted Simulators from cloud coding agents.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Cloud iPhone Simulators for AI agents: build the Xcode project, read the screen, tap by label, test.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables 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.1792-
- AlicenseAqualityBmaintenanceEnables 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.2589 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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