grogu-mcp
Controls unjailbroken iOS/iPadOS devices, providing native UI hierarchy inspection, touch/gesture automation, app launching, screenshots, deep system telemetry, and Siri/Vocal Shortcuts command handling.
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., "@grogu-mcp show me what's currently on my iPhone screen"
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.
Grogu (grogu-ios)
Control unjailbroken iOS / iPadOS devices natively over Tailscale — direct CoreDevice/DVT telemetry, millisecond Decision API, FastWDA UI trees, Siri voice takeover, and MCP integration for LLMs.
Grogu lets a Linux server (or any Tailscale peer) control an unjailbroken iPhone or iPad without keeping a Mac tethered — keeping banking, broker, and Apple Pay apps 100% untampered while giving LLMs and deterministic scripts full native UI hierarchy access and deep system telemetry.
Architecture
flowchart LR
Siri["iOS / iPadOS Siri & Vocal Shortcuts"] -- "POST /api/siri/command (Tailscale)" --> GW["Grogu Gateway (:18830)"]
Agent["LLM / MCP Client"] -- "stdio / HTTP (:18831)" --> MCP["grogu-mcp"]
MCP --> DE["Decision API & FastWDA Client"]
GW --> DE
GW --> Core["GroguCoreManager"]
Core -- "JSON RPC (:18833)" --> Worker["grogu-worker (UserspaceRsdTunnel)"]
DE -- "HTTP (:18832 -> :8100)" --> Worker
Worker <== "Tailscale TCP (:49152 / :62078)" ==> Device["iOS / iPadOS Device"]Four Core Pillars
No-Mac, No-Root Tailscale RSD Tunnel (
grogu-worker)Uses
pymobiledevice3's pure-PythonUserspaceRsdTunneldirectly over Tailscale TCP (RemotePairingport49152orCoreDeviceTunnelProxyover62078) — bypassing mDNS/Bonjour multicast limitations.Clamps
REQUESTED_MTU = 1280for reliable WAN/Tailscale framing and auto-mounts the Personalized Developer Disk Image (auto_mount) whencom.apple.dt.testmanagerd.remoteis absent after a reboot (on high-RTT Tailscale links,sudo pymobiledevice3 remote tunneld+mounter auto-mountcan pre-mount DDI in ~10s).Multiplexes WDA port forwarding (
127.0.0.1:18832 -> device:8100), a shared DVT telemetry RPC socket (127.0.0.1:18833), and anXCUITestServicesupervisor on a single RSD tunnel.
Dual-Speed UI Control (
FastWDAClient+DecisionEngine) — Works Even Without WDAZero-WDA Native Fallback: Before or without WebDriverAgent running,
ios_ui_dump(GET /api/ui/dump) automatically falls back to DVTAccessibilityAudit,launch/open_urlfall back toDvtProviderProcessControl(dvt_launch), and screenshots use DVTScreenshot— zero sideloading required for inspection, deep-link app launching, and voice reading.Full Gesture Mode (
FastWDA): Compacts the XCUITest accessibility hierarchy (type,label,name,value,rect,center) withwaitForIdleTimeout=0andwaitForQuiescence=false.Decision API (
ios_decision_run/POST /api/decision/execute): Executes deterministic steps (launch,open_url,tap,tap_selector,wait_selector,swipe,type,button,sleep,reflex) with per-step millisecond telemetry.Custom On-Device Patch (
wda_patch/): Optional Objective-CFBGroguCommandsextension adding/grogu/fast_treeand/grogu/reflexfor sub-30ms on-device polling and tap synthesis.
Deep System Telemetry (
ios_lowlevel_telemetry/GET /api/telemetry/{kind})summary: Device identity, Developer Mode status, battery, running apps.processes: LiveSysmontapCPU & memory footprint (MB) per PID.ioregistry: Battery capacity, voltage, amperage, adapter watts, temperature, Wi-Fi state.schemes: Installed apps and every registeredCFBundleURLTypesURL Scheme for instant deep-link jumps.oslog: Live unified system logs (ActivityTraceTap).network: UsesPcapdServiceover USB or automatically switches to DVTDeviceInfo.network_information()+NetworkStatisticsover wireless Tailscale RSD.accessibility,dvt_launch,dvt_kill,screenshot.
Non-Blocking Siri & Vocal Shortcuts Takeover (
ios_siri/)POST /api/siri/commandanswers status & screen-read queries synchronously ("speak"), while action commands return an immediate TTS acknowledgment and wait 450ms before injecting UI actions so the Siri overlay dismisses first.Supports both a 60-second Apple Shortcuts + iOS/iPadOS 18+ Vocal Shortcuts setup and native Swift
AppIntents(GroguSiriIntents.swift).
Related MCP server: iphone-mirror-mcp
Quick Start
1. Install on your Linux Tailscale Host
git clone https://github.com/Overbaker/grogu.git
cd grogu
python3 -m venv .venv
.venv/bin/pip install -e ".[worker]"
cp .env.example .env
# Edit .env with your device's Tailscale IP (GROGU_DEVICE_IP) and host Tailscale IP (GROGU_BIND_HOST)Start the gateway (on your Tailscale interface):
GROGU_DEVICE_IP=100.64.0.10 GROGU_BIND_HOST=100.64.0.1 grogu-gateway2. One-Time USB Pairing Bootstrap (on Mac)
Plug your iPhone/iPad into a Mac on the same Tailscale network, unlock it, and run:
curl -fsSL http://<YOUR_GATEWAY_TAILSCALE_IP>:18830/bootstrap/mac.sh | bashThis installs your host's SSH public key, pairs lockdown + RemotePairing over USB, enables Wi-Fi connections, and uploads <udid>.plist + remote_<udid>.plist to ~/.pymobiledevice3/ on your Linux host.
3. Enable Developer Mode & Prepare Sideloader-Compatible WDA (Optional for Touch Injection)
Note: DVT telemetry, wireless
NetworkStatistics,AccessibilityAuditUI trees, app launches, screenshots, and Siri voice queries already work without WDA. Install WebDriverAgent when you also want synthesized touch taps/swipes/typing.
On the iPhone/iPad: Settings → Privacy & Security → Developer Mode → ON (reboot & confirm).
Sideloaders using
apple-codesign(Impactor, AltStore, SideStore,plumesign) skip signingPlugIns/*.xctestbundles (causingmapped file has no cdhash). Repackage the upstream release intoFrameworks/WebDriverAgentRunner.frameworkfirst:
grogu-prepare-wda-ipa --download -o ~/.config/grogu/WebDriverAgentRunner-sideload.ipa The gateway also serves this file over Tailscale at GET /bootstrap/wda-sideload.ipa.
3. Sign & install ~/.config/grogu/WebDriverAgentRunner-sideload.ipa via Impactor, plumesign --apple-id --register-and-install, or Xcode, and trust your developer certificate under Settings → General → VPN & Device Management.
4. Unplug the USB cable and start the persistent tunnel & WDA supervisor (supports both PlugIns/*.xctest and Frameworks/*.framework):
GROGU_DEVICE_IP=100.64.0.10 grogu-worker daemon4. Register as an MCP Server
Add to your MCP client configuration (e.g. mcp_config.json):
{
"mcpServers": {
"grogu-ios": {
"command": "/path/to/grogu/.venv/bin/grogu-mcp",
"args": ["--transport", "stdio"],
"env": {
"GROGU_DEVICE_IP": "100.64.0.10",
"GROGU_BIND_HOST": "100.64.0.1"
}
}
}
}License
MIT © 2026 Overbaker
Available Tools
12 toolsios_decision_runB
Execute a deterministic Decision API JSON step list (launch, open_url, tap, tap_selector, wait_selector, swipe, type, button, sleep, reflex).
Inputs: steps_json (required). Returns: object
ios_input_textB
Type text into the currently focused field.
Inputs: text (required). Returns: object
ios_keyB
Press hardware button: HOME, VOLUME_UP, or VOLUME_DOWN.
Inputs: key_name (required). Returns: object
ios_launch_appB
Launch an app by alias, Bundle ID, or URL Scheme DeepLink.
Inputs: app_target (required). Returns: object
ios_lowlevel_telemetryC
Read low-level iOS/iPadOS telemetry over Tailscale DVT/Lockdownd. Supported kind: summary, processes, ioregistry, schemes, oslog, network, accessibility, dvt_launch, dvt_kill.
Inputs: kind (required), filter_text. Returns: object
ios_screenshotB
Capture screen PNG (via WDA if running, else DVT Screenshot).
Inputs: filename. Returns: object
ios_siri_tasksC
Read recent Siri voice commands & execution traces received by the gateway.
Inputs: limit. Returns: object
ios_statusA
Query device status: Tailscale ports (62078/49152/8100), pairing keys, WDA readiness, and foreground app.
Inputs: no named parameters. Returns: object
ios_swipeC
Swipe from (x1, y1) to (x2, y2) with duration in milliseconds.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +1 more. Returns: object
ios_tapC
Tap at screen point coordinates (x, y).
Inputs: x (required), y (required). Returns: object
ios_tap_elementC
Find a visible UI element by label/name/value and tap its center immediately.
Inputs: text (required), exact. Returns: object
ios_ui_dumpC
Dump current UI accessibility hierarchy cleanly in milliseconds.
Inputs: compact. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool maps to a distinct action on the iOS device, with a clear prefix and scope. The only real overlap is ios_tap vs ios_tap_element (coordinate vs element lookup) and ios_status vs ios_lowlevel_telemetry (both report device diagnostics), but descriptions make the boundaries reasonably clear. ios_decision_run intentionally aggregates primitives, which is fine as an orchestrator.
All 12 tools share the ios_ prefix and snake_case, which is highly predictable. However, the ordering is mixed—verb-first (ios_tap, ios_launch_app, ios_input_text) versus noun-first (ios_status, ios_ui_dump, ios_lowlevel_telemetry, ios_siri_tasks)—so it's not a strict verb_noun pattern throughout.
Twelve tools is well within the sweet spot for an iOS automation server. Every tool earns its place: primitives (tap, swipe, text, key), observation (ui_dump, screenshot, status), and higher-level orchestration (decision_run, launch_app, telemetry).
Coverage is strong: observation, low-level input, app launch, batch orchestration, and telemetry are all present. Minor gaps remain—no standalone app terminate/close (only dvt_kill buried in telemetry), no long-press or element-relative swipe, and no query for installed apps.
Maintenance
Related MCP Connectors
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
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.
Give your AI agent a memory and body on your iPhone: set alarms, ring your phone, over MCP.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to discover and interact with iOS apps through a local MCP gateway, converting remote Streamable HTTP MCP endpoints into stdio tools. Provides dynamic device discovery, tool schema introspection, and deterministic tool calling for app analysis.-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that lets LLMs drive a real iPhone through macOS iPhone Mirroring, with tools for screen capture, OCR, taps, typing, and Xcode build/test/install automation.9MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate a real iPhone from a Mac by reading the screen over USB and sending taps, swipes, typing, and app launches over Bluetooth, with every action returning a fresh screenshot so the agent can verify its work. Runs as a local MCP server, so agents can test iOS apps on physical devices and automate everyday phone tasks.38 npm10MIT
- AlicenseNot gradedqualityCmaintenanceA local MCP server that lets AI agents see and operate real iPhones, iPads, and Android devices from a Mac — screenshots, on-device OCR, taps, swipes, typing, app launching, and replayable skills over USB, Wi-Fi, or adb, with nothing installed on the phone. It gates anything that sends, posts, buys, or deletes behind human approval dialogs and private credential entry, backed by a kill switch, policy file, audit log, and a live-view web console.1GPL 3.0