MCP server Mobdev

Mobdev for Mac

The Mobdev app: your iPhones, iOS simulators and Android devices in one window, for you and your AI agent. Free, open source, about 2 MB, no account.

Mobdev reads the iPhone screen over the USB cable, the way QuickTime does. With Developer Mode on the iPhone and Xcode on the Mac, it builds Mobdev Runner, a small UI test, and keeps it running on the iPhone: the runner taps, swipes, types any text, presses keys and buttons and reads the UI tree, over the same cable. iPhones without Developer Mode are driven over Bluetooth instead, with the Mac posing as a keyboard and pointer; nothing is installed on them. Booted simulators and Android devices take the same tools. Agents get an MCP server and a small HTTP API. An optional relay lets agents elsewhere reach the devices.

              USB cable: screen frames (like QuickTime)
   ┌─────────┐ ◀──────────────────────────────────────────────── ┌────────┐
   │  Mac    │                                                   │ iPhone │
   │ Mobdev  │ ────────────────────────────────────────────────▶ │        │
   │         │   Developer Mode: Mobdev Runner over the cable    │        │
   │         │   (XCUITest: taps, swipes, keys, text, UI tree)   │        │
   │         │ ────────────────────────────────────────────────▶ │        │
   └─────────┘   without it: Bluetooth LE keyboard + pointer     └────────┘
     ▲     ▲     (AssistiveTouch turns the pointer into taps)
     │     └── MCP / HTTP on 127.0.0.1
     │
     └── optional outgoing connection to a relay (see ../relay)

Requirements

• A Mac running macOS 26 or later (the interface uses Liquid Glass). Developed on macOS 27 with Swift 6.4.
• An iPhone and a USB data cable. Charge-only cables give power and no picture.
• To control the iPhone: Developer Mode on it and Xcode on the Mac, signed in with an Apple Account (a free one works). Without Developer Mode: Bluetooth LE on the Mac and AssistiveTouch on the iPhone.
• To build: Xcode 26 or later (Swift 6.2+, macOS 26 SDK).

Build and run

cd macos
MOBDEV_VARIANT=release scripts/build-app.sh   # builds build/Mobdev.app (ad hoc signature)
open build/Mobdev.app                         # allow Camera (and Bluetooth without Developer Mode) when macOS asks

macOS treats the iPhone screen like a camera, hence the Camera prompt. To sign with a certificate, set CODESIGN_IDENTITY; UNIVERSAL=1 builds for Apple silicon and Intel. With an ad hoc signature macOS may ask for the permissions again after each rebuild.

Without MOBDEV_VARIANT=release the script builds Mobdev Dev (build/Mobdev Dev.app) for development. It is a separate app that runs next to an installed Mobdev without changing it: bundle ID dev.mobdev.mac.dev, its own settings and secrets in ~/Library/Application Support/dev.mobdev.mac.dev, port 4687, the mobdev-dev:// URL scheme (so dashboard links keep opening the installed app), the MCP name mobdev-dev, an amber icon and no automatic updates. Both apps share the Mac's Bluetooth, and each starts its own Mobdev Runner on an iPhone in Developer Mode, so quit one before testing input on an iPhone.

Set up the iPhone (once)

On first launch a setup assistant walks through these steps and checks each off as soon as the Mac detects it. It asks for camera access on the page that explains it, and for Bluetooth access only on the way without Developer Mode. Open it again with Mobdev › Set Up iPhone…. Without an iPhone, choose Simulators and Android Only on the welcome page: nothing asks for camera or Bluetooth access until you set one up.

1. Plug it in, unlock it and tap Trust. If the Mac asks to allow the accessory, click Allow. The screen appears in Mobdev.
2. Turn on Developer Mode: Settings › Privacy & Security › Developer Mode, tap Restart, and after the restart tap Turn On and enter the passcode. The switch appears once the iPhone was connected to Xcode (Window › Devices and Simulators). Mobdev reads it from Xcode's device list.
3. Sign in to Xcode with your Apple Account (Xcode › Settings › Apple Accounts; a free account works). Mobdev picks the newest team of the Apple Development certificates in your keychain.
4. Mobdev builds Mobdev Runner and starts it on the iPhone by itself (see Developer Mode control on iPhones); the first build takes a minute or two. If iOS asks, turn on Settings › Developer › Enable UI Automation. With a free account, trust your developer certificate once: Settings › General › VPN & Device Management.
5. Set Auto-Lock to Never while agents work. The phone must stay unlocked.

Without Developer Mode

Choose Without Developer Mode in the setup assistant. Mobdev then taps and types through Bluetooth, posing as a keyboard and pointer, and installs nothing on the iPhone. The same way serves an iPhone whose Developer Mode Control is turned off, and, when the iPhone is paired, stands in while Mobdev Runner is still starting.

1. On the iPhone open Settings > Bluetooth and tap this Mac under Other Devices to pair. iOS lists it by the Mac's name (System Settings › General › Sharing), not as “Mobdev”. An iPhone on the same Apple Account can miss the Mac, because it already knows it from Handoff and trusts the Bluetooth services it cached. Until an iPhone pairs, Mobdev rebuilds its Bluetooth services after 8 seconds and then at doubling intervals up to every 2 minutes, which makes iOS look again. Show on iPhone Again in the setup does it right away.
2. Turn on Settings > Accessibility > Touch > AssistiveTouch. iOS then shows a pointer and turns clicks into taps. On the same page turn off Snap to Item and keep Perform Touch Gestures on. With Snap to Item on, iOS moves the pointer onto the nearest item and every swipe becomes a tap on it. Mobdev checks this without clicking before the first swipe and after a drag in the mirror, shows the result as Pointer in the device panel and in status, and swipe refuses while the pointer snaps.
3. In Mobdev pick the keyboard layout that matches Settings > General > Keyboard > Hardware Keyboard on the iPhone (U.S. or German).

iOS hides its on-screen keyboard while a Bluetooth keyboard is connected, with or without the cable. After five minutes without input Mobdev lets go of Bluetooth, so the iPhone shows its own keyboard again; the next tap or key from Mobdev connects again within a few seconds (MOBDEV_BLUETOOTH_REST_SECONDS changes the five minutes). For ten minutes after an iPhone or iPad is plugged in without pairing, Mobdev stays connected so that it can still pair; Show on iPhone Again connects again after that. Moving the mouse over the mirror connects right away and keeps Bluetooth awake, so the first click goes through without delay. Until the iPhone has connected all of its inputs again, Mobdev refuses input rather than send a click without the pointer move before it.

The mirror in the app is live: click to tap, drag to swipe, swipe with two fingers on the trackpad (sideways too), scroll with the wheel (a sideways wheel or Shift scrolls sideways), and type while it has focus. Over Bluetooth the pointer follows the mouse as it moves; through Mobdev Runner each tap, swipe and scroll goes out when the button or the fingers lift, and typing in short bursts. ⌘V types the Mac clipboard on the phone. The inspector on the right shows what is still missing, Activity lists every agent action, and Settings (⌘,) holds the keyboard layout and API token.

• Apps (in the inspector) lists the apps installed for development, or all of them. Drop an .app, .ipa or .apk on it to install; launch, stop and remove apps; follow an app's console live, open its crash reports and try deep links. It uses the same tools as agents, so it needs Developer Mode and Xcode for an iPhone, and nothing for simulators and Android.
• Diagnose… (under the setup steps and in the device info) checks the cable, the picture, the iPhone's USB screen interface, macOS's screen capture helper, Developer Mode, Mobdev Runner, Bluetooth and AssistiveTouch, and offers the fix for each, such as restarting a stuck capture helper or building the runner again. Bluetooth and AssistiveTouch count only without the runner.
• Projects (at the top of the sidebar) hold an app's tests, flows, screenshots, map, recordings and runs in a folder of its repository; see Projects.
• App Store Connect (in the sidebar, after a key in Settings) shows your apps' builds, TestFlight groups, versions and reviews; see App Store Connect.
• Record and Run Flow… (in the activity header) record and replay flows; see below.
• Inspect (in the toolbar) lays an inspector over the screen: the element under the pointer is outlined with its role, label and identifier, and a click copies the step that taps it, such as {"tap_element":{"id":"login"}}, instead of tapping the device. Simulators, Android, and iPhones with Mobdev Runner.
• Settings › Agents lists apps agents may not open; see Security and privacy.

Connect an agent

The app shows ready-to-copy configurations with the right paths. The stdio variants need no token: Mobdev mcp reads it locally and starts the app in the background if needed. It reaches the app over a Unix socket in the app's data directory rather than the TCP port, so another user on the Mac cannot pose as the app and collect the token.

Claude Code:

claude mcp add --scope user mobdev -- /Applications/Mobdev.app/Contents/MacOS/Mobdev mcp

Codex (~/.codex/config.toml):

[mcp_servers.mobdev]
command = "/Applications/Mobdev.app/Contents/MacOS/Mobdev"
args = ["mcp"]

Claude Desktop, Cursor and other clients:

{ "mcpServers": { "mobdev": { "command": "/Applications/Mobdev.app/Contents/MacOS/Mobdev", "args": ["mcp"] } } }

Clients that speak Streamable HTTP can also use http://127.0.0.1:4686/mcp with Authorization: Bearer <token> (copy it in the app). The server supports MCP 2026-07-28 and the earlier initialize-based versions from 2024-11-05 to 2025-11-25.

Tools

Coordinates are pixels of the image screenshot returns (long edge 1280 px, origin top-left). Actions return a fresh screenshot over MCP unless screenshot is false. With more than one device, pass device (an id or name from list_devices) to pick one. Without it, Mobdev uses the only device, or the connected iPhone when simulators or Android devices run next to it.

Tool	Arguments
list_devices		iPhones, booted simulators and Android devices: id, name, model, system version, ready
list_virtual_devices		Every iOS simulator and Android Virtual Device on the Mac, running or not (see Simulators and Android)
boot_device	id, window	Starts a simulator or AVD and waits until it has booted; it then appears in list_devices
shutdown_device	id	Shuts a simulator down or quits an emulator, unless a flow, test run or crawl holds it
create_simulator	device_type, runtime, name, boot	Makes an iOS simulator, such as "iPhone 17 Pro" on "27.0" (default the newest iOS), and boots it
delete_simulator	id	Deletes a simulator that create_simulator made; others are refused
status		Screen and input readiness, how input reaches an iPhone (Mobdev Runner or Bluetooth), screenshot size
screenshot		JPEG of the screen
tap	x, y, double	x and y may also be shares of the screen such as "50%", as in every tool with coordinates
long_press	x, y, seconds
swipe	from_x, from_y, to_x, to_y, duration
pinch	scale, x, y, duration	Two fingers around a point (default the center) along the screen's longer side, e.g. to zoom a map, photo or plan: scale 2 spreads them to twice their distance and zooms in, 0.5 zooms out. Simulators, Android with scrcpy and iPhones and iPads with Mobdev Runner; not over Bluetooth, which has one pointer
scroll	direction (up/down/left/right), amount, x, y	Mouse wheel over Bluetooth, a swipe elsewhere; right reveals content further right
type_text	text, submit	Into the focused field, at most 1000 characters per call
type_secret	name, submit	Types a stored password or code without the agent seeing it (see Secrets)
list_secrets		The names of the stored secrets, never their values
press_key	key, modifiers, count	e.g. space + cmd for Spotlight; volume_up and volume_down press the buttons (iPhones, Android)
home
open_app	name	By name or bundle ID on simulators, Android and iPhones with Mobdev Runner; through Spotlight on an iPhone over Bluetooth
read_screen		All visible text with positions (on-device OCR)
find_text	text
tap_text	text, index, double, hold	Taps a visible label; double taps twice, hold presses for that many seconds
wait_for_text	text, timeout, gone
observe	image, contains	The screen as numbered marks: UI tree elements, else recognized text; image draws them on a screenshot
tap_mark	mark	Taps a mark from the last observe
scroll_until_visible	text, id, direction, max_scrolls	Scrolls until it shows, stops at the end of the list
wait_for_idle	timeout, stable	Until the screen stops changing, status bar ignored
ui_tree	contains, all	Elements from the accessibility tree: role, label, identifier, value, position. Simulators, Android, and iPhones with Mobdev Runner
tap_element	id, text, regex, role, value, enabled, region, near, index, timeout, double, hold	Taps an element by identifier, label, role, state or the label next to it, waiting up to 5 s for it
wait_for_element	id, text, regex, role, value, enabled, region, near, timeout, gone	Like wait_for_text, from the tree
assert_screenshot	name or path, threshold, mask, compare_status_bar, update	Compares the screen with a baseline picture and fails with a diff; records the baseline when there is none (see Checks)
accessibility_audit	image, fail_on, ignore	Missing labels, small tap targets, low text contrast, duplicate and unclear labels, from the UI tree
assert_with_ai	question, expect	Asks Apple Intelligence on the Mac a yes/no question about the screen
run_flow	path, steps, variables, video	Replays a flow (JSON or Maestro YAML) and stops at the first failing step; video saves a recording (.mp4)
run_tests	project, tests, variables, video, language	Runs a project's tests on this device: every result, the first failure's screen, results.json and junit.xml
list_projects		The projects Mobdev knows, which is active, and which one your calls use
create_project	path, name, bundle_id, builds	Makes a project, such as ~/code/my-app/mobdev, and makes it active; without bundle_id it takes the repository's only app, or lists them
open_project	project	Makes a project active: its folder, a repository with mobdev/, or its name
list_tests	project	A project's tests and its newest results
save_test	project, name, steps, description, platforms, file	Writes a test into the project, creating it when needed
save_flow	project, name, steps, file	Writes a flow into the project's flows/
test_result	project, run	The newest run's results, with each failure's step, screenshot and video
run_native_tests	project, platform, only, workspace, xcode_project, scheme, test_plan, build, gradle_root, task, module, wait	Runs the app's own XCTest/Swift Testing or Gradle suite on this device in the background (see Native tests)
native_test_result	project, run	A native run's progress, else its results: every failure with message and file:line, attachments, the .xcresult
save_screenshot	path	The screen as a full-resolution PNG in the project's screenshots/, such as de-DE/iphone-6.9/01-home
crawl_app	bundle_id, max_actions, max_screens, max_depth, seconds, avoid, output	Explores an app without a model, maps its screens and keeps every crash with the steps to it
navigate_to	bundle_id, screen, map	Goes to a screen the map of crawl_app knows
list_apps	all	Apps installed for development, or every app
install_app	path	A build from a path on this Mac: .app/.ipa for iPhone, .app for simulators, .apk for Android
uninstall_app	bundle_id	Only apps installed for development
launch_app	bundle_id, arguments, environment, restart	Captures what the app prints
stop_app	bundle_id
open_url	url	Deep links, universal links, web pages; confirms iOS's "Open in …?" where there is a UI tree
logs	bundle_id, after, lines, contains	Output of launched apps and how they ended
crash_reports	app, name, limit	Lists reports; name reads one
start_network_capture	bundle_id	Records which requests an app makes (see Network)
network_log	bundle_id, contains, after, limit, query, headers	The recorded requests: method, URL, status, bytes each way, duration and where it was seen
stop_network_capture	bundle_id	Ends the capture; on Android it removes Mobdev's proxy from the device
mock_response	url, status, body, content_type, clear	Android: a fixed answer for plain HTTP requests through the proxy
set_location	latitude, longitude, route, speed, clear	A simulated position, or a route the device follows
set_permission	bundle_id, permission, state	Grant, revoke or reset location, photos, contacts, camera and more without the prompt
send_push	bundle_id, title, body, badge, data, payload	A push notification to a simulator app
set_appearance	dark, text_size, increase_contrast, reduce_motion	Dark mode, Dynamic Type and accessibility switches
set_language	language, bundle_id	e.g. de-DE: the simulator's, or one Android app's
set_status_bar	preset, time, battery_level, battery_state, wifi_bars, cellular_bars, network	screenshot gives 9:41 and full bars; clear resets
biometrics	action (match/fail/enroll/unenroll)	Answers a Face ID, Touch ID or fingerprint prompt
reset_app	bundle_id, keychain	Deletes an app's data as if just installed
clipboard	text	Reads the clipboard, or sets it to text
set_orientation	orientation	portrait, landscape_left, landscape_right, portrait_upside_down
start_recording	path	Records the screen to an .mp4 until stop_recording, by default into the project's output/recordings
stop_recording		Ends the recording and says where it is
recent_steps	count, clear	The newest actions that worked, as flow steps for save_test
run_shortcut	name	Runs a shortcut from Apple's Shortcuts app
performance	bundle_id, seconds, max_cpu, max_memory_mb, max_janky_percent	CPU, memory and (Android) frames of a running app; budgets fail the call. iPhones through Instruments
measure_launch	bundle_id, runs, method, max_ms, stable	Cold launch time over several runs: min, median, max
record_trace	template, seconds, bundle_id, launch, path	An Instruments trace (iPhones, simulators) or a Perfetto trace (Android) into the project's output/traces, with a short summary
device_load	count	The whole device: busiest processes by CPU and memory, memory used and total, thermal state
dev_menu	port	Opens a React Native or Expo app's developer menu
reload_app	port	Reloads a React Native or Expo app through Metro, else through its developer menu

Text recognition uses Apple's Vision framework on the Mac; no screen content leaves the machine unless your agent sends it to its model. Each recognition runs in a fresh process (Mobdev __text), and moves to the CPU when the Neural Engine fails. If it fails anyway, the text tools answer from the UI tree on simulators, Android and iPhones with Mobdev Runner and say so. Without a tree, they say that recognition failed and suggest screenshot.

From the terminal

Mobdev call <tool> runs one tool from a shell, for scripts and for agents that prefer a terminal to MCP; Mobdev <tool> key=value … is short for it and Mobdev tools lists the tools. Values are JSON where they parse as JSON and text otherwise:

M=/Applications/Mobdev.app/Contents/MacOS/Mobdev
$M observe
$M tap_mark mark=4
$M type_text text="hello world" submit=true
$M screenshot --image screen.png
$M call set_location '{"latitude": 52.52, "longitude": 13.405}' --device "iPhone 17"

It goes through the running app, so it reaches iPhones too and shows in Activity; without the app, or with --local, it runs by itself on booted simulators and Android devices, like Mobdev flow. --json prints the whole result, --image saves a returned screenshot, and --project names the project that gets what the tool saves (default: the project of the current folder, see Projects). It exits 0 when the tool succeeded, 1 when it reported an error and 2 when it could not run. start_recording, tap_mark, network capture and other calls that build on an earlier one need the app.

Secrets

Passwords and codes of test accounts go into Settings › Secrets, or Mobdev secret set <name>. Agents type them with type_secret and know only the name: the value is not in the result, the activity, recorded flows and tests, or recent_steps. They are kept in secrets.json, readable only by you (mode 0600), next to the API token. Agents through a relay may type a secret only when its Relay box is on.

M=/Applications/Mobdev.app/Contents/MacOS/Mobdev
$M secret set test-password                                  # asks for the value without showing it
printf '%s' "$TEST_PASSWORD" | $M secret set test-password   # in CI, from a secret variable
$M secret list
$M secret remove test-password

{"tap_element": {"id": "password"}},
{"type_secret": {"name": "test-password", "submit": true}}

A test project's secrets in mobdev.json take the stored secret of the same name, such as PASSWORD, when neither the run nor the environment sets it, so an agent can run a sign-in test without knowing the password. Mobdev flow and Mobdev test read them from Mobdev's folder, also when --artifacts takes their logs elsewhere. A password field hides the value on screen; a plain text field shows what it holds in screenshots and the UI tree.