Skip to main content
Glama
Sign In
brickproof-adb

brickproof-adb

by st412m
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

brickproof-adb

Let an AI assistant look after your own Android devices — TV boxes first, phones and tablets too — over ADB, without bricking them.

brickproof-adb is an MCP server. It gives Claude (or any MCP client) the screen, the input and the package manager of your devices, and puts guard rails where a careless call would hurt: every package change is a dry run first, the packages a device cannot live without are read off the device and refused, a package that serves something on your network right now is not touched, and everything applied goes into a snapshot that one call rolls back.

It runs on Windows, macOS and Linux, in Docker, and as a Home Assistant app; devices connect over USB or the network.

What it looks like

Finding the TV.

You: Find my TV.

Claude calls adb_devices discover=true. Nothing is connected yet; the search looks for devices that announce debugging and for port 5555 on the home network:

Found:
  192.0.2.50:5555 (port 5555 open, network debugging) - adb_connect host=192.0.2.50:5555; if this computer is new to the device, it asks on its screen to allow debugging

Claude: I found one device at 192.0.2.50. Shall I connect? The TV will ask whether to allow debugging.

You: Yes.

Claude calls adb_connect host=192.0.2.50:5555; you confirm the prompt to allow debugging on the TV screen, with "Always allow" checked. The address is remembered and connected again whenever the server starts.

Installing what you just downloaded.

You: Install on the TV the app I just downloaded.

Claude calls adb_install without a path and gets the newest installable files of your Downloads folder, then adb_install with the first one: a report of what would be installed on which device. After your yes, the same call with dry_run=false installs it.

Cleaning up a TV box.

You: The box is slow. Turn off the preinstalled junk, but nothing it needs.

Claude calls adb_app action=list filter=system, picks five packages and calls adb_app action=disable with them. That is a dry run by default: the plan comes back with the rollback path of each package — and one package refused, because the box uses it as its launcher:

REFUSED: the list contains protected packages - com.example.launcher.
  com.example.launcher — launcher, roles (HOME)
The full set with every source: adb_app action=protected
Nothing was applied. Remove them from the list by hand; the tool has no override.

Claude drops it, runs the plan for the other four, then repeats it with dry_run=false. The account count and the launcher are checked after the batch, and the four packages are recorded in the snapshot.

You: The voice remote stopped working.

Claude calls adb_app action=restore, reads the plan and repeats it with dry_run=false: the four packages are enabled again in one call.

Seeing the screen and tapping.

You: Open the network settings on the phone.

Claude calls adb_screenshot, gets the picture and the line under it:

screen 1080x2340 -> image 473x1024 · scale 2.283/2.285 · pass coords="screenshot" to adb_tap/adb_swipe

and taps the "Network & internet" row it sees, with adb_tap coords="screenshot", in the image's own coordinates. On a TV box without a touchscreen it uses adb_find_and_tap text="Network", which walks the focus there with the remote's keys.

Related MCP server: adb-tv-mcp

Install it where your AI is

Details, other setups and checks: docs/installation.md. An AI app without MCP support cannot use this server.

  • Home Assistant — install the ha-adb-mcp app. It is reachable from a browser chat through your Home Assistant's external address.

  • Claude Desktop (Windows, macOS) — download the .mcpb file from the latest release and drag it into the Claude Desktop window, or choose it in Settings → Extensions → Advanced settings → Install Extension… (a double click works too, unless an archiver opens the file instead); Claude Desktop shows a short form and installs it. No Node.js needed. A JSON configuration instead: docs/installation.md.

  • Claude Code:

    claude mcp add brickproof-adb -- npx -y brickproof-adb

  • Other MCP clients on your computer — the server command is npx -y brickproof-adb.

  • A chat in the browser without Home Assistant — needs a computer at home that stays on, running brickproof-adb serve, behind a public HTTPS address: docs/installation.md.

  • Docker — ghcr.io/st412m/brickproof-adb: docs/installation.md.

First run

  1. Turn on debugging on the device. Android TV, Google TV, Fire TV and phones hide it under Developer options, which appear after tapping the build number seven times in the About screen of the settings. There: USB debugging for a cable; Network debugging or ADB debugging on many TV boxes; Wireless debugging on a phone with Android 11 or newer.

  2. Tell the assistant "find my TV" (or phone). It searches the network and suggests what to connect; a phone on a cable shows up by itself.

  3. Confirm the prompt to allow debugging on the device screen, with "Always allow" checked. A phone over Wi-Fi asks for the pairing code shown on its screen instead.

Defaults that need no setting: files go to and from your Downloads folder, connected devices are remembered, and adb is found by itself (or brickproof-adb get-adb downloads it).

Requirements

  • Node.js 22.17 or newer — for every setup except the Claude Desktop extension, Home Assistant and Docker.

  • adb (Android SDK Platform-Tools): found by itself where Android Studio, WinGet, Homebrew or your system put it, or downloaded with brickproof-adb get-adb. Docker and Home Assistant bring their own.

  • A device with debugging on, over USB or the network.

Connecting

Over stdio (Claude Desktop, Claude Code) there is nothing to connect: the client starts the server. Over HTTP (brickproof-adb serve) the token goes either in the path or in a header:

https://<your-host>/private_<token>/mcp
Authorization: Bearer <token>

The token is generated on the first start; brickproof-adb token shows it again, brickproof-adb token --new replaces it. See docs/security.md.

Tools

18 tools. Semantics, refusals and time limits: docs/tools.md; screen geometry and input: docs/screen-and-input.md.

  • adb_devices — connected and remembered devices; discover=true searches the network

  • adb_connect — connect a network device, ip or ip:port; remembered for the next start

  • adb_disconnect — drop one network device (and forget it), or all

  • adb_pair — pair an Android 11+ device over Wireless debugging

  • adb_shell — any shell command; off unless allow_shell is set

  • adb_logcat — recent log lines, filtered on the device

  • adb_screenshot — the screen as JPEG, with the scale to tap by

  • adb_ui_dump — on-screen elements with tap coordinates

  • adb_tap — tap a point, in screen or screenshot coordinates

  • adb_swipe — swipe or long-press

  • adb_key — a key press (HOME, BACK, DPAD_CENTER…)

  • adb_text — type into the focused field, Unicode through ADBKeyBoard

  • adb_find_and_tap — find an element by its label and activate it

  • adb_install — install an APK, a split set or an .apks/.xapk/.apkm bundle; dry run by default; without a path, lists what can be installed

  • adb_uninstall — remove an app by package name

  • adb_app — package operations with guard rails, snapshot and rollback

  • adb_push — copy a file to the device

  • adb_pull — copy a file from the device

Safety

What protects your devices, and what does not: docs/safety.md. In short: dry runs by default, a protected set read off the device, a network guard on live services, an account canary between batches, a snapshot with one-call rollback, and adb_shell and uninstalling off until you turn them on. No tool changes these switches; you do, with brickproof-adb set or in the settings of your app.

Limitations

  • ADB is not a sandbox. With allow_shell on, adb_shell can do anything the device's shell user can, past every guard.

  • The search finds devices on the same network only: a guest network, Wi-Fi client isolation or separate VLANs hide them. In Docker and Home Assistant only TV boxes on port 5555 are found; phones connect by the address on their screen.

  • The tool list is cached per chat; after an update start a new chat.

  • A screenshot of a sleeping device is a dark frame, and the answer says screen: Asleep; adb_key key=WAKEUP wakes it, and HDMI-CEC may then switch on the television.

  • Content protected with FLAG_SECURE (streaming players, banking apps) shows as a black frame.

  • Snapshots live on the machine that made them: a rollback has to run where the change was made.

  • USB devices in Docker work only on a Linux host.

License

MIT

Available Tools

18 tools
adb_appManage packagesA
Destructive

Package operations with guard rails: inspect, launch, stop, clear, disable, uninstall, back up and restore packages. Use it rather than adb_shell or adb_uninstall for package changes. Every action that changes packages defaults to dry_run=true. A protected set derived from the device (launcher, active IME, installer, WebView provider, role holders, account packages) aborts the whole call on any overlap, and has no override. A network guard refuses disable, uninstall, stop and clear while the package is serving an off-device client, naming the port and the peer. Only force_network=true lifts it; force covers a failed APK backup and nothing else. An account canary between batches rolls a batch back and stops on a drop. Everything applied goes into a snapshot, so action=restore undoes it. mode=uninstall also needs the server option allow_uninstall and a successful APK backup. action=launch also accepts uri and/or intent_action for an intent or deep link; CALL, CALL_PRIVILEGED and CALL_EMERGENCY are refused while allow_shell is false.

Inputs: action (required), q, uri, mode, +13 more.

adb_connectConnect deviceA
Idempotent

Connect to a device over network ADB. host is ip or ip:port (default port 5555). An Android 11+ phone with Wireless debugging is paired once with adb_pair first; after that adb_connect is enough. The reverse is adb_disconnect.

Inputs: host (required).

adb_devicesList devicesA
Read-onlyIdempotent

List connected Android devices with serial, state and description (adb devices -l), and remembered addresses that are not connected now. Start here: the other tools take serial from this list. If the device the user means is not in the list, call again with discover=true: it searches the local network for devices to connect (mDNS and port 5555), any time and as often as needed, and connects none of them.

Inputs: discover.

adb_disconnectDisconnect deviceA
Idempotent

Disconnect a network ADB device, the reverse of adb_connect. Omit host to disconnect every network device. adb_disconnect then adb_connect recovers a device that adb_devices lists as offline. With host the address is also forgotten and not reconnected at start.

Inputs: host.

adb_find_and_tapFind and tap elementA

Find an on-screen element by text, resource-id or content-desc and activate it. The method is derived from the device: with a touchscreen the element centre is tapped; on leanback without one the focus is walked there with DPAD keys, since a coordinate tap activates whatever has focus. If the focus stalls, cycles, or the target is not reached in max_steps or the time budget, nothing is pressed and the tool reports where it stopped. Prefer it over adb_ui_dump plus adb_tap when the label is known; use adb_tap for a point that has no label.

Inputs: desc, text, exact, index, +3 more.

adb_installInstall appA
Destructive

Installs only with dry_run=false; by default it reports what would be installed and installs nothing. Installs an APK from the server's file roots (file_roots). apk_path takes a single .apk, an array of split-APK paths, or one .apks/.xapk/.apkm bundle. Without apk_path it installs nothing and lists the installable files in file_roots, newest first, with the full path to pass as apk_path: start there when the user says "install what I downloaded". Bundle splits are chosen from the device ABI list, density and locale. No matching ABI split is a refusal; a density mismatch is not. Flags -r, -t and -g are applied by default. The reverse is adb_uninstall, or adb_app for a removal with a backup and a rollback.

Inputs: abi, dir, serial, density, +3 more.

adb_keySend keyA

Send a keyevent. Accepts names (HOME, BACK, ENTER, DPAD_UP, POWER, VOLUME_UP, MENU, TAB...) or numeric codes. On TV boxes DPAD_UP/DOWN/LEFT/RIGHT move the focus and DPAD_CENTER presses it. verify="activity"|"ui" reports whether the key changed anything; see adb_tap for the same parameter. For text use adb_text; for a labelled element, adb_find_and_tap.

Inputs: key (required), serial, verify.

adb_logcatRead logcatA
Read-onlyIdempotent

Read recent logcat lines without waiting for new ones, e.g. to see why an app crashed; unlike adb_shell it works with allow_shell off. filter: either a logcat filterspec like "ActivityManager:I :S" (contains ":" or ""; *:S is auto-appended if missing so unmatched tags are silenced) or a plain substring grepped case-insensitively across the whole line. lines limits the result (default 200). Filtering runs on the device.

Inputs: lines, filter, serial.

adb_pairPair deviceA

Pair with an Android 11+ device over Wireless Debugging, once per device and computer; afterwards adb_connect alone reconnects. On the device: Developer options -> Wireless debugging -> "Pair device with pairing code" shows ip:port and a 6-digit code. The pairing port is random and differs from the connect port; after pairing succeeds, call adb_connect with the ip:port shown on the main Wireless debugging screen.

Inputs: code (required), host (required).

adb_pullPull file from deviceA
DestructiveIdempotent

Copy a file from the device into the server's file roots (file_roots), overwriting a file of the same name and creating missing directories. The reverse is adb_push.

Inputs: host_path (required), device_path (required), serial.

adb_pushPush file to deviceA
DestructiveIdempotent

Copy a file from the server's file roots (file_roots) to the device, overwriting a file of the same name there. To install an APK use adb_install instead. The reverse is adb_pull.

Inputs: host_path (required), device_path (required), serial.

adb_screenshotTake screenshotA
Read-onlyIdempotent

Take a screenshot of the device screen. Returns a JPEG image, then a text line with the logical screen size, the image size and the scale between them, e.g. "screen 1080x2340 -> image 473x1024 · scale 2.283/2.285". Pass coords="screenshot" to adb_tap/adb_swipe to tap coordinates read off that image. A near-uniformly dark frame is a warning after the image, not a refusal. To read labels and exact tap points, adb_ui_dump is cheaper and precise; the screenshot shows what the dump cannot (images, video, games).

Inputs: max_px, serial, quality.

adb_shellRun shell commandA
Destructive

Run a shell command on the device (settings, pm, am, dumpsys, getprop, wm, cmd, svc...) and return stdout. It bypasses every guard rail, so it works only while the server option allow_shell is on. For package changes use adb_app instead: dry runs, a protected set, a network guard and a rollback snapshot.

Inputs: command (required), serial, timeout_sec.

adb_swipeSwipeA

Swipe from (x1,y1) to (x2,y2) over duration_ms (default 300). The same point at both ends with duration_ms >= 800 is a long-press. coords and verify work as in adb_tap and both endpoints share one coordinate space; with verify="ui", an "unchanged" result on a swipe usually means the end of a scrollable list. On a TV box without a touchscreen, move the focus with adb_key DPAD_* instead.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +4 more.

adb_tapTapA

Tap at (x, y). coords="screen" (default): coordinates from adb_ui_dump, the logical space input tap uses. coords="screenshot": coordinates off the last adb_screenshot for the SAME serial, rescaled; missing or older than 120s is refused. Rotation between screenshot and tap is not checked. verify="activity"|"ui" reports whether the tap changed anything; a failed verify never turns a performed tap into an error. To activate an element by its label, adb_find_and_tap does it in one call and also works on TV boxes without a touchscreen.

Inputs: x (required), y (required), coords, serial, +1 more.

adb_textType textA

Type text into the focused input field. Focus the field first; on a TV box, DPAD_CENTER on the field opens the keyboard. For single keys (ENTER, BACK) use adb_key. ASCII goes through input text; non-ASCII (Cyrillic, emoji, CJK) is sent via the ADBKeyBoard IME, which must be installed on the device (github.com/senzhk/ADBKeyBoard): the current keyboard is switched to it and restored afterwards. The response reports only the character count, never the text itself. Never retry a wrong password or PIN: repeated failures can lock the account or device. Stop and ask the user.

Inputs: text (required), serial.

adb_ui_dumpDump UI hierarchyA
Read-onlyIdempotent

Dump the current UI hierarchy (uiautomator) as a compact list of interactive/labeled elements with tap coordinates @(x,y). Password fields are marked [PASSWORD] and listed even with no visible text. Use together with adb_tap. Prefer it over adb_screenshot for labels and tap targets; use adb_screenshot for content the dump does not see (images, video, some WebViews and games).

Inputs: serial.

adb_uninstallUninstall appA
DestructiveIdempotent

Uninstall an app by package name, at once and without a backup. keep_data=true keeps app data (-k). The reverse is adb_install. For system packages, reversible bulk operations and backups, use adb_app.

Inputs: package (required), serial, keep_data.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools target a distinct action+resource, and descriptions explicitly steer selection (e.g. adb_ui_dump vs adb_screenshot, adb_tap vs adb_find_and_tap). There is deliberate overlap in package operations (adb_app, adb_install, adb_uninstall) and UI tapping (adb_tap vs adb_find_and_tap), but the guidance on when to prefer each largely resolves it.

    Naming Consistency5/5

    Every tool follows the same adb_verb_noun snake_case pattern (adb_ui_dump, adb_install, adb_pull, adb_logcat). No mixed conventions or stray naming styles.

    Tool Count4/5

    18 tools is slightly on the heavy side but each covers a genuine sub-domain: connection (devices/connect/pair/disconnect), UI interaction, package management, file transfer, shell and logs. Nothing is redundant enough to feel padded.

    Completeness4/5

    The surface covers the ADB lifecycle well: discovery/connection, UI automation, package management with rollback, file transfer, shell and logcat. Minor gaps exist (e.g. port forwarding, reboot, app data inspection) but they are workarounds rather than blocking omissions.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-android-emulator

      Anjos2
      A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with Android devices and emulators via ADB, providing tools for screenshots, UI inspection, touch and text input, app management, and device control.
      42
      204 npm
      21
      MIT

    • adb-tv-mcp

      mosesmrima
      A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to control Android TV/Android devices through ADB, including screen capture, remote control, app management, and more.
      24
      14 npm
      3
      MIT

    • tvlm

      smartago
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to drive an Android TV or Google TV box end to end through named tools — discover, pair, connect, check, install, provision, link, test, screenshot, report and a gated shell — with usage instructions embedded in the tool descriptions so the agent never improvises adb. Every command passes the same safety gate that refuses destructive actions.
      15
      Apache 2.0

    • TV Box Tools

      smartago
      A
      license
      Not graded
      quality
      B
      maintenance
      Set up Android TV, Google TV and Fire TV boxes over ADB on the local network: discover and pair boxes, set any launcher as the HOME app, install apps, take screenshots and run checks. No raw shell tool; the tools that change the box ask before they run.
      Apache 2.0