agent-device
OfficialThis server exposes agent-device as an MCP toolset for controlling, inspecting, debugging, and testing apps across mobile, TV, web, and desktop targets.
Manage devices and sessions: list devices, boot/shutdown, check capabilities, open/close apps, install/reinstall/uninstall, list apps, and inspect app state.
Inspect UI state: capture accessibility snapshots and diffs, find/read elements, check predicates, wait for text/selectors/stable UI, and take screenshots.
Interact with apps: click/press/long-press, fill/type/focus, scroll/swipe/gesture, back/home/app switcher, hardware buttons, TV remote, alerts, keyboard, and clipboard.
Debug and profile: collect logs, network traffic, performance traces, recordings, traces, crash symbols, React Native overlay help, and app-defined events.
Automate and test: run/replay scripts, run test suites, batch commands, record scripts, manage sessions/artifacts, and simulate telephony/push notifications.
Control device/platform state: orientation, foldable poses, settings/permissions, web viewport, and remote/cloud provider artifacts.
Automates Android emulators and devices, enabling app opening, UI accessibility tree inspection, element interaction (fill, tap), and evidence collection (screenshots, videos, logs, CPU/memory/perf).
Enables testing of Expo apps on iOS and Android, including opening Expo Go or dev clients, UI snapshotting, element interaction, and gathering evidence such as screenshots, videos, logs, and performance traces.
Automates iOS simulators and devices, enabling app opening, UI accessibility tree inspection, element interaction, and evidence collection (screenshots, videos, logs, network, performance).
Automates Linux desktop applications, enabling UI inspection via accessibility snapshots, element interaction, and evidence collection (screenshots, logs, performance).
Automates macOS desktop applications, enabling UI inspection via accessibility snapshots, element interaction, and evidence collection (screenshots, logs, performance).
agent-device
Open source device layer for AI coding agents. Let coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud, through a CLI, built-in MCP server, or typed Node.js API.
Let your coding agent verify its changes in the running app. agent-device lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the AI SDK or Eve. Developers at Expensify, Shopify, and others use it to verify their apps.
Quick start
Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See Installation for target requirements.
npm install -g agent-device@latest
agent-device doctor
agent-device help workflowRun doctor yourself before you hand the CLI to an agent. help workflow links to the guides for debugging, replay, and profiling.
Drive an app from the CLI
Add a contact in the built-in iOS Contacts app:
# Start a session.
agent-device open Contacts --platform ios
# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"
# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"
# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device closeRefs are valid only in the latest output: after a --settle command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.

Add MCP tools to your agent
agent-device mcp starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:
{
"mcpServers": {
"agent-device": {
"command": "agent-device",
"args": ["mcp"]
}
}
}See AI agent setup for per-client setup and when to prefer plain CLI over MCP.
Script it from Node.js
createAgentDeviceClient() gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code:
import { createAgentDeviceClient } from 'agent-device';
const client = createAgentDeviceClient({ session: 'qa-run' });
try {
await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
const snapshot = await client.capture.snapshot({ interactiveOnly: true });
const button = snapshot.nodes.find((node) => node.role === 'button');
if (button) await client.interactions.press({ ref: button.ref });
} finally {
await client.sessions.close();
}See the Node.js API, the runnable examples, and the AI SDK and Eve integration guides.
Related MCP server: Taproom
What agents can do
Inspect app state through accessibility snapshots, refs, and selectors, and profile React Native renders to find what makes an interaction slow.
Act on visible UI by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts.
Diagnose failures with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
Repeat workflows by saving working steps as
.adscripts for local use or CI. Export strict Maestro YAML when needed.
See Commands for the commands and evidence each target supports.
What to ask your agent
With the CLI installed, prompts like these work end to end:
"Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots."
"Reproduce this crash and capture the logs that lead up to it."
"Check whether this change causes unnecessary React Native re-renders."
"Explore the checkout flow once, save it as a replay script, and run it in CI."
"Verify this pull request on a physical device and attach reviewable evidence."
Next steps
AI agent setup: skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
Quick start: open an app, read its UI, and interact with it from the command line.
Replay and E2E testing and Debugging and profiling: repeatable tests and bug hunting.
Where to run agent-device
The same session and evidence model works at every step: the agent explores the app, captures evidence, saves a replay, runs it in CI, and moves onto remote devices.
Path | Best for | Start with |
Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the EAS workflow template. |
Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a remote proxy, connect a device cloud (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or contact Callstack for team QA. |
How it works
agent-device keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android, Android TV, and Fire OS; HDC and ArkUI uitest on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS, including Electron and other Chromium-based apps through the accessibility tree; and AT-SPI on Linux.
Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run agent-device capabilities --platform <platform> to see what a target supports. The capabilities matrix shows which commands each target, desktop, web, and cloud provider supports.
Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Run agent-device device status to inspect ownership without a daemon, and agent-device device release --stale to release claims whose owner is provably no longer running. The same commands drive hosted devices on BrowserStack, AWS Device Farm, TestMu AI, and Limrun.
agent-device uses the inspect-act-verify process from Vercel's agent-browser for mobile, TV, and desktop apps. Basic --platform web support runs agent-browser in the same session and replay system.
FAQ
What is agent-device?
agent-device is a command-line tool and MCP server that lets AI coding agents inspect, control, and verify mobile apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
Is there an MCP server for mobile app automation?
Yes. agent-device mcp starts the official stdio MCP server. The Quick start above has the client config, and AI agent setup covers per-client details.
Does it work with React Native, Expo, Flutter, and native apps?
Yes. agent-device supports native iOS and Android apps, plus React Native, Expo, and Flutter apps on supported targets. The commands and evidence vary by target.
How is it different from mobile MCP servers?
The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three.
Can I build my own agent or QA product on agent-device?
Yes. The typed Node.js client is a public surface over that same runtime, so an agent you build inherits everything above. Start from the Node.js API, AI SDK, or Eve guides.
How is it different from Appium, Detox, or Maestro?
With agent-device, an agent reads app state and chooses each command at run time. For stable, repeatable test suites, use e2e, a TypeScript testing framework for web and mobile apps. agent-device can also save its runs as .ad scripts or export them as strict Maestro YAML.
Can agent-device run in CI?
Yes. Record a run as an .ad script, replay it in CI, and keep the screenshots and logs as artifacts; the EAS workflow template is a working example.
Articles and videos
Articles
Videos
Who uses agent-device?
Teams and developers at Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and others use agent-device.
Documentation
Contributing
See CONTRIBUTING.md.
Made at Callstack
agent-device is open source under the MIT license. Visit agent-device.dev or contact Callstack.
Available Tools
63 toolsaction-buttonPress the iPhone or iPad Action ButtonADestructive
Press the iPhone or iPad Action Button once. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the app keeps the state the press found. What the system does with the press is not observed by this command: Simulators run no Shortcuts or App Intents, so delivery to an assigned Shortcut is verifiable only on a physical iPhone. A model with no Action Button refuses with UNSUPPORTED_OPERATION, error.details.reason hardware_control_unavailable and dispatched: no. Times out after 90s.
Inputs: udid, device, serial, session, +3 more.
alertInspect, accept, or dismiss a platform alertADestructive
Inspect, wait for, accept, or dismiss a platform alert. The get action reads alert content; accept and dismiss change the active alert state. Each iOS XCTest execution activates once, then only observes. Apple XCTest and Limrun iOS choose recognized English labels by preference (Allow While Using App before Allow Once); on iOS simulators, including Limrun, the runner also recognizes the device's preferred languages' wording of those labels from the OS permission-prompt strings, on any alert; equal-ranked choices and unknown labels refuse, including a lone unknown button. Open, Done, and Confirm… accept; Keep Browsing, Deny, and Skip dismiss. On the Apple XCUITest runner, dismiss taps only a recognized decline label (Cancel, Don't Allow, Ask App Not to Track, and similar) or the close element of a popover whose accessibility marker reads exactly "dismiss popup"; when no button fits the action, accept and dismiss answer ALERT_BUTTON_NOT_FOUND having tapped nothing. The get action exposes labels for explicit button targeting. The timeout argument is the poll window only for wait: a wait polls its whole window, accepted up to 2147453647 ms, and a longer one is refused before anything runs with details.reason: alert-wait-window-too-long and details.maxWaitWindowMs, never shortened. On the Apple XCUITest runner, get takes the same argument as the runner's read budget (10 s by default, at least 1.5 s, at most 25 s); other backends' get ignores it. For wait, the first XCTest read uses the requested window capped at 25 s; later reads use the remaining window with the same cap, without the 1.5 s floor. Every backend's accept and dismiss run their own retry window and ignore the argument. A get the runner's watchdog (the same budget) cuts off answers runner_main_thread_timeout with dispatched: unknown, which does not mean no alert; the next get waits out RUNNER_BUSY while abandoned work drains, and still answers RUNNER_BUSY (dispatched: no) if that outlasts the bounded resends. A get result with status none reports no alert. An alert-not-found refusal means no alert was found and no button was pressed. An alert-wait-timeout means no actionable alert resolved within the wait window. A refusal with dispatched: no means no button was activated. After a press, an unconfirmed outcome leaves the resulting alert state unknown. Times out after 90s; a caller-supplied budget extends it.
Inputs: udid, action, device, serial, +5 more.
appsList installed apps or deferred provider app assetsC
List the apps installed on the selected device. The appsFilter input includes or excludes system and OEM apps. Times out after 90s.
Inputs: udid, device, serial, session, +3 more.
appstateShow the foreground app and activityA
Show foreground app/activity (Android and HarmonyOS; iOS and macOS answer per session) Times out after 90s.
Inputs: udid, device, serial, session, +2 more.
app-switcherOpen the device app switcherA
Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app. Times out after 90s.
Inputs: udid, device, serial, session, +3 more.
artifactsList daemon or cloud provider session artifactsARead-only
List daemon or cloud provider artifacts for an active or completed session. Times out after 90s.
Inputs: udid, device, serial, session, +4 more.
audioProbe audio levelsA
Measure browser or host-rendered simulator/emulator audio as compact dBFS buckets. Probe actions start sampling, report its status, or stop sampling. Times out after 90s.
Inputs: udid, action, device, serial, +6 more.
auditReport advisory accessibility findingsA
Report advisory accessibility findings from one fresh capture of the current screen: touch targets below the platform recommendation, controls without an accessible name, and controls the snapshot already marks covered. Findings are review prompts, not failures, and the audit changes nothing on the device. Times out after 90s.
Inputs: udid, device, serial, session, +2 more.
backNavigate back in the app or systemA
Navigate back in the app or through system navigation. The in-app mode targets the app navigation stack; system targets platform back behavior. iOS has no system back: both modes only pop the navigation stack and never close a modal or sheet, whose own Close or Cancel control does; Android's system back also closes dialogs and modal screens. On iOS, back presses the navigation bar system back button (identifier BackButton) only when exactly one hittable one is found in a readable accessibility tree, and succeeds only when the bar count, the back button count, or a back button title then changes; a back button with no title, such as the iPhone Duo's floating one, is confirmed by its bar's title instead, which must hold still before the tap, and a bar that retitles itself can be misread as a pop. Otherwise it swipes from the left edge (on an iPad whose app window cannot be resolved, only while the app fills the screen) and succeeds only when the app screen changes. Reason back_swipe_no_change: the swipe was sent and the screen did not change; details.dismissControls then lists the top-band Back, Close, Cancel, or xmark buttons (never Done or Save) as { selector, label, identifier? }, and the hint names a lone one. Press one by its selector; back returns no refs, because it expires them. Reason back_swipe_unverified: the button was pressed but the bar did not change within 1 s or on one more read, or the swipe may or may not have navigated because the screen kept changing before it or could not be sampled after it. Reason back_swipe_not_dispatched, or a screen that cannot be sampled before the swipe, means nothing was sent. An app with a left-edge drawer may open the drawer instead. Times out after 90s; a caller-supplied budget extends it.
Inputs: mode, udid, device, serial, +7 more.
batchRun multiple commandsADestructive
Execute multiple commands in one daemon request. Use it for a known multi-step walk, such as press A, press B, back, instead of one tool call per step. steps is an array of {command, input} objects; input takes the same arguments as that command's own tool (ref, selector, or x and y for targets; settle: true for the settled diff). Steps run serially in one session; onError: "stop" halts at the first failing step, and the result reports the steps that ran. The daemon stops the whole batch after 60 seconds; split longer walks. Example steps, in order (refs such as @e12 come from the last snapshot or settled diff): {"command":"press","input":{"ref":"@e12","settle":true}}, {"command":"press","input":{"selector":"label=Settings","settle":true}}, {"command":"fill","input":{"selector":"id="field-email"","text":"qa@example.com"}}, {"command":"scroll","input":{"direction":"down","until":"label=Privacy","settle":true}}, {"command":"back","input":{"settle":true}}, {"command":"wait","input":{"kind":"text","text":"Saved"}}, {"command":"snapshot","input":{"interactiveOnly":true}}. Times out after 90s.
Inputs: steps (required), out, udid, device, +6 more.
bootBoot target device/simulatorA
Boot or prepare the selected device or simulator so later commands can target it. The device is chosen through the device-selection inputs, not by naming it here. On Limrun, allocate or reuse an instance. Existing-instance credentials attach without creating one. Times out after 90s; a caller-supplied budget extends it.
Inputs: pick, udid, device, serial, +5 more.
capabilitiesList supported commands for the selected deviceARead-only
List the commands supported by the selected device or active session. Device-selection inputs support capability checks without an open session. Times out after 90s.
Inputs: udid, device, serial, session, +2 more.
clickClick or tap a UI targetADestructive
Activate a UI target by snapshot ref, selector, or coordinates. This can change app state. Success reports dispatch only; settle returns the resulting UI diff and verify returns cheap post-action evidence. A ref or selector target is re-checked for motion before dispatch when the session's previous action just animated the screen, and is dispatched at its resting position; one that has not stopped refuses with target_still_moving rather than acting where it was. With settle, continue from the returned diff. Copy refs exactly, including any ~sN suffix. Times out after 90s; a caller-supplied budget extends it.
Inputs: x, y, raw, ref, +21 more.
clipboardRead or write device clipboard textADestructive
Read the current device clipboard text, or replace its contents with the given text. Android runs both through the clipboard service shell command, and a build that implements none (Android 16 does not) refuses with UNSUPPORTED_OPERATION rather than reporting an empty clipboard. Times out after 90s.
Inputs: action (required), text, udid, device, +5 more.
closeClose an app or end the sessionADestructive
Close the named app, or close the active session app when app is omitted. The shutdown option also stops the session simulator or emulator where supported; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s; a relaunching open accepts that new process. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running. If close cannot confirm its cleanup on a session that holds a device claim, the session and its claim stay. A repeated close retries cleanup with the same options, except that save-script must be omitted after publication. Times out after 90s.
Inputs: app, udid, force, device, +7 more.
debugSymbolicate Apple crash artifactsA
Symbolicate Apple crash artifacts with matching dSYM UUIDs. This command handles Apple crash symbolication only. Times out after 90s.
Inputs: action (required), artifact (required), out, dsym, +7 more.
devicesList available devices and simulatorsARead-only
List available devices and simulators that can be selected for automation. Results include the platform, device name, and available platform-specific identifiers for selection. Times out after 90s.
Inputs: udid, device, serial, session, +2 more.
diffDiff snapshot or screenshotB
Compare accessibility snapshots or screenshots to identify UI changes. Snapshot comparisons report semantic tree changes; screenshot comparisons report pixel differences. Times out after 90s.
Inputs: kind (required), out, raw, udid, +9 more.
doctorDiagnose device, app, dev-server, and RN/Expo readinessA
Diagnose device, app, development-server, and React Native or Expo readiness issues. Returns compact evidence for local inventory, sessions, optional app discovery, toolchains, and server reachability. On iOS simulators it also warms the XCTest runner build cache in the background when missing. Times out after 90s.
Inputs: udid, device, remote, serial, +4 more.
eventsRead session event timelineBRead-only
Read the daemon-owned session event timeline as paged JSON-friendly entries Times out after 90s.
Inputs: udid, limit, cursor, device, +4 more.
fillReplace text in a UI inputADestructive
Replace text in a UI input selected by snapshot ref, selector, or coordinates. An empty text clears the field. Unconfirmed evidence does not establish the resulting value or screen. The recordAs option keeps sensitive text out of a recorded replay while sending it to the live app. To append instead of replacing, use type. Times out after 90s; a caller-supplied budget extends it.
Inputs: text (required), x, y, raw, +18 more.
findFind an element and actADestructive
Find by text/label/value/role/id and run action; the action defaults to click. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window. The focus and type actions aim at a text field: the match or the field holding it, even beside other fields, or else the one enabled on-screen field inside the match. Several enabled on-screen fields inside the match refuse with AMBIGUOUS_MATCH and the field candidates, and a disabled target refuses with reason target_disabled. Web text boxes are not recognized as text fields. Times out after 90s.
Inputs: query (required), raw, last, udid, +13 more.
focusFocus input at screen coordinatesA
Move input focus to explicit screen coordinates without entering text. This command changes focus only and does not enter or replace text. Times out after 90s.
Inputs: x (required), y (required), udid, device, +5 more.
foldFold or unfold a foldable iPhone simulator or Android emulatorA
Fold or unfold a foldable iPhone simulator (iPhone Duo) or a foldable Android emulator into the closed, half-open, or open pose. iOS sends a simulator HID hinge event, then reads the hinge angle back inside the simulator to confirm it, and can follow timestamped angle keyframes; Android sets the emulator console posture, then confirms the device state the guest commits and reports the angle read from the hinge sensor, which can differ from the AVD profile's per-posture angles, and dismisses the lock screen a fold to the cover display can raise. On iOS a pose change moves the app to a different panel with a different point size; on Android a fold to or from closed moves the app between the cover and inner displays, and any pose change can reshape the app window, whose size the next snapshot reports. Either way every ref and coordinate from before it is stale. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator and emulator only; iOS requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required. An iOS simulator in a scoped simulator set folds the same way as one in the default set. Times out after 255s.
Inputs: pose, udid, device, serial, +5 more.
gestureRun pan, fling, swipe, pinch, rotate, transform, tap, or drag gesturesBDestructive
Perform a structured pan, fling, swipe, pinch, rotate, transform, tap, or drag gesture. Each gesture kind has its own inputs. A tap touches 2 to 5 points at once; count and pauseMs control repetition. Times out after 90s.
Inputs: kind (required), udid, count, delta, +22 more.
getRead element text or attributesA
Read text or accessibility attributes from a snapshot ref or selector without changing the app. The text format returns visible content; attrs returns the element attribute map. Times out after 90s.
Inputs: format (required), raw, ref, udid, +11 more.
hardware-buttonPress a phone hardware button onceA
Press a phone hardware button once: volume-up, volume-down, power, mute, sleep, wake, media-play-pause, media-next, media-previous, media-rewind, or media-fast-forward. The press is dispatched without activating the session app and nothing is re-observed afterwards, so the OS decides what the key does — which audio stream a volume press moves, which media session a media key reaches, and whether the HUD shows, is device behavior this command does not claim. Power toggles the Android screen; sleep and wake are the explicit Android events that turn it off or on without toggling, and after a press that turns it off, later commands may hit a locked screen. Android (ADB-backed and Appium) presses all eleven on phones and tablets; a physical iPhone or iPad presses volume only through the local runner or Appium, never power, mute, sleep, wake, or media. iOS Simulators, Android TV and tvOS targets refuse this command. Times out after 90s.
Inputs: button (required), udid, device, serial, +4 more.
helpRead usage guidesARead-only
Return usage guides and command references. With no topic, returns the root decision card. The topic can be commands, manual-qa, maestro, workflow, scripting, gestures, tv, debugging, react-devtools, cdp, react-native, physical-device, ios-system-ui, foldable, remote, macos, web, dogfood, validate, or a tool name for its complete flag reference.
Inputs: topic.
homeGo to the device home screenA
Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app. Times out after 90s.
Inputs: udid, device, serial, session, +3 more.
hoverHover the pointer over a UI target (web only)A
Move the pointer over a UI target by snapshot ref, selector, or coordinates without pressing, to reveal hover-gated UI such as row toolbars or menus. Web only; touch platforms have no hover state. The settle option returns the UI diff revealed by the hover. Times out after 90s; a caller-supplied budget extends it.
Inputs: x, y, raw, ref, +14 more.
installInstall an app binary from a pathBDestructive
Install an app binary from a local path. An app identifier alongside the path selects the app explicitly when required by the target. Local Android and iOS install steps time out after 120s; the command allows 480s including device startup. Times out after 480s.
Inputs: appPath (required), app, udid, device, +10 more.
install-from-sourceInstall app builds from URLs or CI artifactsADestructive
Install app builds from URLs, remote source specs, or CI artifacts resolved by a remote daemon. The command allows 600s, including up to 120s for the download; local Android and iOS install steps time out after 120s. Times out after 600s.
Inputs: source (required), udid, device, serial, +6 more.
isCheck a UI predicate on a selectorA
Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. absent passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. This command checks the current condition without polling. Times out after 90s.
Inputs: selector (required), predicate (required), raw, udid, +10 more.
keyboardInspect, press, or dismiss the device keyboardADestructive
Report or act on the device keyboard. The status action reports whether the keyboard is visible and, when it is, what its return key offers: returnKey is go, search, send, next, done, previous, join, route, continue, enter, none, or unknown, and returnKeyLabel is the wording that return key itself shows when the platform can read it, trimmed of surrounding whitespace, which can be an app's custom or a localized string. A label appears only for a key the platform identified as the return key. none means the field offers no action key, which only Android can establish; unknown means this read could not name the key, not that the keyboard has one: on iOS the identified key carries wording this read does not map, or the keyboard exposes no return key it can identify at all — a number, decimal or phone pad has none, and then no label is reported either; on Android the editor's imeOptions name no action. A hidden keyboard reports neither field. The get action answers the same as status. The dismiss action hides the keyboard. It taps the keyboard dismiss/hide key when one is exposed, verifies the keyboard closed, and reports UNSUPPORTED_OPERATION when the keyboard stays up — background taps are never attempted. On iOS a keyboard with no dismiss key adds error.details.reason keyboard_dismiss_unavailable with dispatched: no; one whose key was tapped and stayed visible has no reason and dispatched: unknown. Android reports keyboard_dismiss_unavailable with dispatched: unknown, since its own dismiss keyevents were already sent. The enter action presses the return key. Times out after 90s.
Inputs: udid, action, device, serial, +4 more.
logsManage session app logsCDestructive
Session app log info, start/stop streaming, diagnostics, and markers Times out after 90s.
Inputs: udid, action, device, serial, +5 more.
longpressHold a UI target to open a context menuBDestructive
Hold a UI target by snapshot ref, selector, or coordinates to open a context menu or perform another hold gesture. The durationMs input overrides the default hold duration. Times out after 320s; a caller-supplied budget extends it.
Inputs: x, y, raw, ref, +15 more.
metroPrepare the dev server or reload appsBDestructive
Prepare a React Native development server or ask connected apps to reload, using the development server this session is bound to. Explicit runtime inputs override that binding for one call. The binding is cleared when the session closes, and a fresh open without runtime hints also clears any leftover binding from a previous same-name session. Times out after 90s.
Inputs: action (required), kind, port, udid, +21 more.
networkInspect HTTP(S) traffic from session logsC
Dump recent HTTP(s) traffic parsed from the session app log Times out after 90s.
Inputs: udid, limit, action, device, +5 more.
openOpen an app, deep link or URL, save replaysADestructive
Boot the selected device when needed, then open an app, deep link, or URL in a session. With a known app, start with open and foreground: a fresh open returns the initial interactive snapshot with refs (or initialSnapshotError: then run snapshot). Do not probe with devices or apps first; list them only for an unknown app id, and never guess one. The app or URL inputs select the foreground automation target. Remote daemons refuse file: URLs in open targets and launch URLs with reason REMOTE_HOST_INPUT_DENIED. Local web content is supported over HTTP(S). metroHost, metroPort, and bundleUrl choose the app's Metro server and save its address for later reloads. launchUrl selects the app's launch URL and does not select the reload server. A fresh open without Metro hints clears an older same-name binding; close also clears it. Times out after 90s; a caller-supplied budget extends it.
Inputs: app, url, udid, force, +25 more.
orientationSet device orientationB
Set device orientation on iOS and Android. auto hands rotation back to the sensor on ADB-backed Android (local and Limrun); other backends refuse it. In both default and scoped simulator sets, an iPhone Duo classified with more than one integrated panel refuses portrait-upside-down and rotates through the fold helper; it succeeds only when the lit panel shows the requested orientation, otherwise it fails with orientation-unverified, or orientation-panel-table-unavailable when the final guest panel table cannot be read. A simulator classified with one panel, or whose first classification read is unresolved, uses the standard runner rotation. Times out after 90s.
Inputs: orientation (required), udid, device, serial, +4 more.
perfCheck frames, memory, or native profilesA
Collect frame health, memory diagnostics, and platform profiling artifacts with compact agent-readable summaries. For CPU profiles, start and stop write the raw artifact while report writes a compact summary for readable native CPU evidence. Profiling output is evidence only: compact state, artifact path, and size. Times out after 90s.
Inputs: area (required), out, kind, udid, +10 more.
pressShort-press a UI targetADestructive
Short-press a UI target by snapshot ref, selector, or coordinates. Success reports dispatch only; settle returns the resulting UI diff and verify returns cheap post-action evidence. A ref or selector target is re-checked for motion before dispatch when the session's previous action just animated the screen, and is dispatched at its resting position; one that has not stopped refuses with target_still_moving rather than acting where it was. A comma-separated ref list dispatches 2-16 keys in order as one command, admitted before the first press. Times out after 90s; a caller-supplied budget extends it.
Inputs: x, y, raw, ref, +20 more.
pushDeliver a push notification payloadBDestructive
Deliver push notification payloads to an installed app. Times out after 90s.
Inputs: app (required), payload (required), udid, device, +5 more.
react-nativeRun React Native automation helpersA
Run supported React Native automation helpers. The dismiss-overlay action closes a visible React Native warning or error overlay. Times out after 90s.
Inputs: action (required), udid, device, serial, +4 more.
recordStart or stop screen recordingC
Start or stop a screen recording for the active app session or, where supported, the selected device, or build a contact-sheet PNG from a recording already exported. Long Android recordings can return multiple video artifacts; HarmonyOS supports whole-screen recording on physical devices. Times out after 90s.
Inputs: action (required), fps, path, udid, +9 more.
reinstallReplace an installed app with a new buildADestructive
Replace an installed app with a binary from a local path. This preserves the app identity while installing a new build on the selected device. Local Android and iOS install steps time out after 120s; the command allows 480s including device startup and uninstall. On iOS, a corrupt .ipa that cannot be unpacked leaves the installed app in place. On Android, an archive that cannot be unpacked or contains no .apk or .aab also leaves it in place. An invalid app bundle, corrupt APK or another install failure after uninstall can still leave the app removed. Times out after 480s.
Inputs: app (required), appPath (required), udid, device, +10 more.
replayReplay a recorded session or Maestro flowBDestructive
Run a recorded automation script, including compatible Maestro YAML flows. A script without a terminal close leaves its session active for subsequent automation. Times out after 90s; a caller-supplied budget extends it.
Inputs: path (required), env, udid, force, +17 more.
screenshotCapture a screenshotA
Capture a screenshot of the active app or web session. Input fields control capture scope, density, size, and annotations. Use it for visual evidence, or when a snapshot warns that the accessibility tree is sparse: read the image, then press by coordinates. A screenshot alone does not verify a result. Times out after 90s.
Inputs: path, udid, scale, cropOn, +14 more.
scrollScroll in a direction or to an edgeA
Scroll in a direction, or toward the top/bottom edge of scrollable content. The until input scrolls to an off-screen selector in one command. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, where a settle observation or a replay already owns that observation, or where the operator opted out of it. Times out after 90s; a caller-supplied budget extends it.
Inputs: direction (required), udid, until, amount, +12 more.
sessionList sessions, show the state dir, or publish a scriptBDestructive
List active sessions, print the effective daemon state directory, or publish an armed open-to-destination script without closing its session Times out after 90s.
Inputs: path, udid, force, action, +5 more.
settingsChange OS settings and app permissionsBDestructive
Read or change supported operating-system settings, animation scales, appearance, or app permissions on the selected target. Platform support varies by setting and action. Times out after 90s.
Inputs: setting (required), app, mode, udid, +10 more.
shutdownShutdown target simulator/emulatorADestructive
Shutdown a selected simulator or emulator. On Limrun, delete a created instance or release an attachment. Apps and data on a deleted instance are lost. A Limrun connection without an instance fails with DEVICE_NOT_FOUND and details.reason provider_instance_unallocated and creates nothing. Times out after 90s.
Inputs: udid, device, serial, session, +2 more.
snapshotCapture or diff the accessibility treeA
Capture the accessibility tree or compare it with the previous session baseline. The result includes refs for semantic interactions; the diff option reports UI changes. interactiveOnly lists only elements you can act on. After an action with settle, take a snapshot only when its diff lacks the next target or did not settle. Times out after 90s; a caller-supplied budget extends it.
Inputs: raw, udid, depth, scope, +12 more.
swipeFling between coordinatesB
Quick coordinate fling with optional repeat pattern. Times out after 90s.
Inputs: to (required), from (required), udid, count, +8 more.
telephonySimulate an incoming call or SMS on an Android emulator over adbADestructive
Simulate an incoming phone call or SMS on an Android emulator through its console over adb: call rings from the number, accept answers, cancel ends the call, and sms delivers a text message. The call screen or notification can cover the app and invalidate earlier UI observations. Times out after 90s.
Inputs: action (required), number (required), text, udid, +6 more.
testRun replay test suitesCDestructive
Run one or more replay scripts as a serial test suite Streams progress; no fixed client timeout.
Inputs: paths (required), env, udid, device, +18 more.
traceStart or stop trace captureA
Start or stop trace-log capture and return the resulting artifact when capture ends. Without a path, start writes a timestamped trace log named after the session in the sessions directory of the daemon state; a path on stop moves the finished trace there. Times out after 90s.
Inputs: action (required), path, udid, device, +5 more.
trigger-app-eventInvoke an app-defined automation eventBDestructive
Ask the app to handle an app-defined automation or test event, with an optional structured payload. Supported event names and payload shapes are defined by the app. Times out after 90s.
Inputs: event (required), udid, device, serial, +5 more.
tv-remotePress a TV remote navigation, media, or hardware buttonADestructive
Press or long-press a TV remote button on Android TV, tvOS, or Vega OS. Android TV also supports volume, power, media, channel, guide, captions, input, color keys, and android-keycode:N. tvOS and Vega OS support up, down, left, right, select, menu, home, and back. Phones and WebDriver sessions are unsupported. The aliases ok, center, and enter map to select. Times out after 90s.
Inputs: button (required), udid, device, serial, +5 more.
typeAppend text to the focused inputADestructive
Append text to the currently focused input. This requires an active input and preserves its existing text. Times out after 90s.
Inputs: text (required), udid, device, serial, +5 more.
uninstallRemove an installed appBDestructive
Remove an installed app from the selected device. A package name or bundle id that is not installed succeeds with wasInstalled: false. The command allows 480s including device startup. Times out after 480s.
Inputs: app (required), udid, device, serial, +9 more.
viewportResize the active web viewport for the current sessionA
Resize the active web viewport before taking snapshots or screenshots. Resizing can reveal different content in fixed-layout or 100vh apps. Times out after 90s.
Inputs: width (required), height (required), udid, device, +5 more.
waitWait for a duration, text, selector, strict absence, or stable UIA
Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Text matches a label, identifier, or value; an editable field never matches by its current value or by a label that only repeats it, so text you typed does not satisfy it. The strict absence target requires zero selector matches; stable waits until the UI stays quiet for the requested window. Use it to verify an expected result, such as text that appears after a network call, instead of polling with snapshot. Times out after 90s; a caller-supplied budget extends it.
Inputs: raw, ref, kind, text, +15 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
Many tools legitimately overlap in purpose: click, press, find (whose action defaults to click), and gesture's tap all activate UI targets, while fill/type/focus all touch text inputs and scroll/swipe/gesture all move content. The descriptions do draw careful boundaries (dispatch-only vs settle vs verify, append vs replace, coordinate fling vs structured gesture), so an agent can usually disambiguate, but the distinctions are buried in dense prose rather than self-evident from names.
Most tools are lowercase verbs (click, fill, snapshot, wait) with kebab-case compounds (app-switcher, hardware-button, install-from-source), which is fairly predictable. But the convention is broken by one-word compounds that should be kebab (appstate vs app-switcher, longpress), odd verb-ish names (is, type, back, help), and noun-only tools (apps, devices, logs, events, artifacts, session) mixed among imperatives.
At 63 tools this is well past the point where a flat surface is easy to navigate, and several clusters (install/reinstall/uninstall/install-from-source, snapshot/get/diff/is/wait, click/press/gesture/swipe) inflate the count. The breadth reflects a genuinely large device-automation domain, but the set would benefit from consolidation or grouping.
Coverage is exhaustive for a mobile/web device automation domain: lifecycle (boot/shutdown/open/close), input, assertions (is/wait/diff), evidence (snapshot/screenshot/record/perf/logs/network/trace), app management (install/uninstall/reinstall/push), and backend-specific niceties (fold, tv-remote, telephony, action-button). Almost no dead ends remain for an agent working through a UI test flow.
Maintenance
Related MCP Connectors
Read-only discovery for AgentWorld WORLD, A2A onboarding and the separate MARKET service economy.
Search, fetch, lint, and install Agent Skills (SKILL.md) from the SkillMD registry.
Discovery for the agent ecosystem: findable businesses, tools, knowledge, agent spaces, skills.
Discover agents, services and capabilities; preview and route work. Discovery is free.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceActs as a unified dispatch hub for local coding agent CLIs, supporting capability-based routing, schema validation, and retries via MCP tools.MIT
- AlicenseNot gradedqualityDmaintenanceDiscovers and manages portable agent capabilities (skills and MCP servers) from configurable collections, providing search, inspection, and local installation via CLI and MCP tools.1MIT
- FlicenseAqualityBmaintenanceActs as a personal AI development environment manager, enabling workspace bootstrapping, headless skill and bundle installation, global caching, and health diagnostics.727 npm-
- FlicenseAqualityCmaintenanceExposes Justworx devices to AI agents as MCP tools and resources, backed by the public Developer API. Supports local stdio and hosted remote OAuth operation for controlling device IO, rules, and viewing live state.6-