List installed package names. filter = case-insensitive substring. only_third_party excludes system apps; include_paths returns {package, apk}.

Launch an app by package via its LAUNCHER intent (idempotent). Returns {package, pid, status}.

Start an explicit activity, e.g. 'com.app/.MainActivity' (am start -n). Returns the am output and resulting pid if resolvable.

Force-stop an app (idempotent). Returns {package, status}.

Kill an app's background processes (am kill, gentler than force-stop).

Clear ALL app data for a package (destructive: wipes saves/cache/prefs).

Return {package, pid, running} for a package.

Return the currently focused activity/package (foreground app).

Return structured package info: versionName, versionCode, targetSdk, minSdk, installer, firstInstall/lastUpdate times, and granted runtime permissions.

Install an APK, or a split-APK set via install-multiple when >1 path given. replace=-r, grant_permissions=-g, downgrade=-d. Returns {status, message}.

Uninstall a package. keep_data=True keeps data/cache dirs (-k).

Grant a runtime permission, e.g. 'android.permission.CAMERA' (pm grant).

Revoke a runtime permission (pm revoke).

Enable or disable a package (pm enable / pm disable-user).

Start a service by component 'pkg/.Service' (am startservice).

Send a broadcast intent (am broadcast -a <action>). Optional target component and string extras {key: value}.

List attached devices/emulators with state and transport.

Returns [{serial, state, is_usb, model, device, transport_id}]. is_usb is False for network devices (serials containing ':', e.g. WSA/emulators).

Return the connection state of a device: device / offline / unauthorized.

Return the host adb client version string and the resolved adb path.

Return the target environment: model, manufacturer, abi, android release, sdk level, build fingerprint, and screen info. Tells the agent exactly what it is targeting before acting.

Return effective display size and density: {width, height, density, raw}.

Prefers the Override size (what input coordinates map to) when set.

Return battery level/status/health/temperature (from dumpsys battery).

adb connect ip:port — attach a network device (WSA, emulator, wireless).

adb disconnect a network device (or all if host_port omitted).

Block until the device is online (or timeout). Useful after reboot/connect.

Reboot the device. mode: '' (normal), 'recovery', 'bootloader', or 'sideload'.

Set the session default device serial (overrides ADB_SERIAL for later calls). Pass an empty string to clear it.

Return the currently active default device serial (runtime or ADB_SERIAL).

Restart adbd as root (adb root). Only works on rooted/userdebug builds; on production builds use su via read_file(as_root=True) etc. instead.

Restart adbd without root (adb unroot).

Remount /system (and other partitions) read-write (adb remount). Needs root.

List a device directory: [{name, size, is_dir, is_link, perms}]. as_root uses su -c ls on rooted devices. Symlinked dirs (e.g. /sdcard on Samsung) are dereferenced so their contents are listed, not the link.

Check whether a path exists on the device. Returns {exists, is_dir}.

Return stat info for a device path: {size, mtime, perms, uid, gid} (best-effort).

Pull a file/dir from the device to host path local.

Push a host file local to device path remote.

Read a text file from the device (up to max_bytes). as_root uses su -c cat (WSA/Magisk). Returns {remote, truncated, content}.

Write text content to a device file by pushing a temp file (handles any content safely, unlike shell echo). as_root pushes to /data/local/tmp then su -c cp into place. Returns {status, remote, bytes}.

Create a directory on the device (mkdir -p).

Delete a device file or (recursive=True) directory. DESTRUCTIVE. Refuses obviously dangerous roots like '/', '/system', '/data'.

Tap the screen at pixel (x, y).

Long-press at (x, y) for duration_ms (implemented as a zero-distance swipe).

Swipe from (x1,y1) to (x2,y2) over duration_ms. Use for scrolling/flinging.

Drag (slow swipe) from (x1,y1) to (x2,y2). Alias of swipe with a longer default.

Type a string into the focused field. Spaces and shell-special characters are escaped so the literal text is entered.

Send a key event. Accepts a numeric keycode or a name like BACK, HOME, ENTER, TAB, DEL, APP_SWITCH, VOLUME_UP (KEYCODE_ prefix optional).

Press the HOME button.

Press the BACK button.

Open the recent-apps / overview screen (APP_SWITCH).

Press the POWER button (toggles screen on/off).

Press ENTER.

Wake the screen and swipe up to dismiss a non-secure lock screen.

Start a background logcat capture to a temp file. Read it with logcat_dump/ logcat_filter; end it with logcat_stop. Only one capture runs at a time. buffers optionally selects e.g. 'main,system,crash'.

Stop the background logcat capture started by logcat_start.

Return recent logcat lines as records {time, pid, tid, level, tag, message}.

Reads the running capture's buffer if active, else does a one-shot logcat -d. tags = filter by tag substring(s); priority = min level V/D/I/W/E/F; message_contains = substring filter on the message; tail = newest N records.

Convenience: logcat_dump filtered to the given tags (e.g. ['Unity','libc','DEBUG']).

Clear the device logcat ring buffers (logcat -c).

Dump the 'crash' logcat buffer (native + Java crashes), newest tail records.

Pull the most recent ANR trace file (/data/anr/traces.txt or /data/anr/). Returns {status, local, size} (needs root/permission on some devices).

Capture a full bugreport zip to local_path (slow; can take minutes).

Capture a screenshot and return it as an inline PNG image. If save_path is given, also writes the PNG there. Ideal for an observe->decide->tap loop / OCR.

Capture a screenshot and save it to save_path, returning {status, path, bytes} (no inline image — use when you only need the file).

Capture a screenshot and return {format, bytes, base64} — for when a raw base64 payload is preferred over an inline image.

Start recording the screen on-device (screenrecord runs in the background). time_limit_s caps duration (screenrecord max 180s per segment). size like '720x1280' to downscale. Call record_screen_stop to finish and pull the mp4.

Stop the background screen recording, pull it to local_path, and clean up the on-device file. Returns {status, local, size}.

adb forward tcp:local tcp:remote — forward a HOST port to a DEVICE port (host connects locally, traffic reaches the device).

adb reverse tcp:device tcp:host — map a DEVICE port to a HOST port so the app's 127.0.0.1:<device_port> traffic reaches your PC (e.g. a local API/CDN shim).

List active adb forward rules: [{serial, local, remote}].

List active adb reverse rules: [{remote, local}].

Remove a single adb forward rule for tcp:local_port.

Remove a single adb reverse rule for tcp:device_port.

Remove ALL forward and reverse rules for the device.

Return the device's IPv4 address on an interface (default wlan0).

Enable/disable Wi-Fi via svc wifi (may need root on newer Android).

Enable/disable mobile data via svc data (may need root on newer Android).

Toggle airplane mode (settings + broadcast). May need root on newer Android.

Read a single system property by name, or ALL props as a dict when name is omitted (parses getprop).

Set a system property (setprop). Many props are read-only or need root.

Read an Android setting. namespace = 'system' | 'secure' | 'global'.

Write an Android setting. namespace = 'system' | 'secure' | 'global'.

List running processes (ps -A): [{pid, ppid, name, user}]. filter = name substring.

Return memory info. With a package: that app's total PSS (kB); otherwise the global summary (Total/Free/Used/Lost RAM). Returns parsed fields + raw text.

Return a one-shot top snapshot of the top count processes by CPU (raw text).

Return device uptime (seconds + human string) from /proc/uptime and uptime.

Run dumpsys <service> for a NAMED service (e.g. 'battery', 'wifi', 'activity', 'meminfo', 'connectivity') and return the raw text (capped). Scoped to a service name — not an arbitrary shell.

List all dumpsys service names available on the device.

Run an arbitrary device shell command. DISABLED by default — set the env var ADB_MCP_ALLOW_SHELL=1 to enable. Prefer the specific scoped tools; this exists only as an explicit, opt-in escape hatch. Returns {rc, output}.

Dump the current on-screen view hierarchy as a flat list of elements {text, resource_id, content_desc, class, clickable, enabled, bounds:{...,center_x,center_y}}.

non_empty_only drops nodes with no text/id/description (usually layout containers); clickable_only keeps only clickable nodes.

Find on-screen elements matching any of text / resource_id / content_desc. Substring match by default; exact=True requires a full match. Returns the same element records as dump_ui, each with a bounds.center for tapping.

Find an element (by text/resource_id/content_desc) and tap its center. index selects among multiple matches. Returns the matched element + tap point.