io.github.st412mPublished by GitHub account st412mv1.0.0Updated Nov 4, 2026
Maintain your own Android devices and TV boxes over ADB with dry runs, guards and rollback
Controls your own Android phones, tablets and TV boxes over ADB: screen, taps, keys, apps and files, with dry runs and rollback.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
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.
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: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_installwithout a path and gets the newest installable files of your Downloads folder, thenadb_installwith the first one: a report of what would be installed on which device. After your yes, the same call withdry_run=falseinstalls 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 callsadb_app action=disablewith 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: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 withdry_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: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 usesadb_find_and_tap text="Network", which walks the focus there with the remote's keys.
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:
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.
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).
brickproof-adb get-adb. Docker and Home Assistant bring their own.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:
The token is generated on the first start; brickproof-adb token shows it again, brickproof-adb token --new replaces it. See docs/security.md.
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 networkadb_connect — connect a network device, ip or ip:port; remembered for the next startadb_disconnect — drop one network device (and forget it), or alladb_pair — pair an Android 11+ device over Wireless debuggingadb_shell — any shell command; off unless allow_shell is setadb_logcat — recent log lines, filtered on the deviceadb_screenshot — the screen as JPEG, with the scale to tap byadb_ui_dump — on-screen elements with tap coordinatesadb_tap — tap a point, in screen or screenshot coordinatesadb_swipe — swipe or long-pressadb_key — a key press (HOME, BACK, DPAD_CENTER…)adb_text — type into the focused field, Unicode through ADBKeyBoardadb_find_and_tap — find an element by its label and activate itadb_install — install an APK, a split set or an .apks/.xapk/.apkm bundle; dry run by default; without a path, lists what can be installedadb_uninstall — remove an app by package nameadb_app — package operations with guard rails, snapshot and rollbackadb_push — copy a file to the deviceadb_pull — copy a file from the deviceWhat 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.
allow_shell on, adb_shell can do anything the device's shell user can, past every guard.screen: Asleep; adb_key key=WAKEUP wakes it, and HDMI-CEC may then switch on the television.Source: README.md at commit 597c6bb
List devices
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.
discoverConnect device
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.
hostrequiredPair device
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.
coderequiredhostrequiredDisconnect device
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.
hostRun shell command
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.
serialcommandrequiredtimeout_secTake screenshot
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).
max_pxserialqualityDump UI hierarchy
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).
serialTap
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.
xrequiredyrequiredcoordsserialverifySwipe
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.
x1requiredx2requiredy1requiredy2requiredcoordsserialverifyduration_msType text
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.
textrequiredserialSend key
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.
keyrequiredserialverifyFind and tap element
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.
desctextexactindexserialmax_stepsresource_idInstall app
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.
abidirserialdensitydry_runlocalesapk_pathUninstall app
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.
serialpackagerequiredkeep_dataPush file to device
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.
serialhost_pathrequireddevice_pathrequiredPull file from device
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.
serialhost_pathrequireddevice_pathrequiredRead logcat
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.
linesfilterserialManage packages
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.
qurimodeforcescopestoreactionrequiredbackupcanaryextrasfilterserial+5 more90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
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 debuggingREFUSED: the list contains protected packages - com.example.launcher. com.example.launcher — launcher, roles (HOME)The full set with every source: adb_app action=protectedNothing was applied. Remove them from the list by hand; the tool has no override.screen 1080x2340 -> image 473x1024 · scale 2.283/2.285 · pass coords="screenshot" to adb_tap/adb_swipeclaude mcp add brickproof-adb -- npx -y brickproof-adbhttps://<your-host>/private_<token>/mcpAuthorization: Bearer <token>