brickproof-adb

brickproof-adb

让 AI 助手通过 ADB 管理你自己的 Android 设备——先支持电视盒子，也支持手机和平板——同时避免把设备变砖。

brickproof-adb 是一个 MCP 服务。它让 Claude（或任何 MCP 客户端）能够查看设备屏幕、输入内容并管理软件包，同时设置防护措施，避免因不谨慎的调用造成损害：每次软件包变更都会先进行试运行；设备不可或缺的软件包会从设备上读取并拒绝操作；当前为网络提供服务的软件包不会被触碰；所有已执行的操作都会记录到快照中，只需一次调用即可回滚。

它可在 Windows、macOS 和 Linux 上运行，也支持 Docker 和 Home Assistant 应用；设备可通过 USB 或网络连接。

使用示例

查找电视。

你： 找到我的电视。

Claude 调用 adb_devices discover=true。目前尚未连接任何设备；搜索会查找正在广播调试信息的设备，以及家庭网络中开放了 5555 端口的设备：

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： 找到一台设备，地址为 192.0.2.50。要连接吗？电视会询问是否允许调试。

你： 是。

Claude 调用 adb_connect host=192.0.2.50:5555；你在电视屏幕上确认允许调试，并勾选“始终允许”。服务器每次启动时都会记住并重新连接该地址。

安装刚下载的内容。

你： 在电视上安装我刚下载的应用。

Claude 先在没有指定路径的情况下调用 adb_install，获取“下载”文件夹中最新的可安装文件；然后针对第一个文件再次调用 adb_install，查看要在什么设备上安装哪些内容。你确认后，它会用 dry_run=false 再次调用同一工具完成安装。

清理电视盒子。

你： 电视盒子很慢。关闭预装的垃圾应用，但别动它必需的内容。

Claude 调用 adb_app action=list filter=system，挑选五个软件包，然后调用 adb_app action=disable。默认情况下这只是试运行：返回的计划会列出每个软件包的回滚路径，其中一个软件包被拒绝操作，因为电视盒子用它作为启动器：

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 将其移除，为其余四个软件包执行计划，然后用 dry_run=false 再次执行。批量操作后会检查用户数量和启动器，并将这四个软件包记录到快照中。

你： 语音遥控器不能用了。

Claude 调用 adb_app action=restore，读取计划后用 dry_run=false 再次执行：一次调用即可重新启用这四个软件包。

查看屏幕并点击。

你： 在手机上打开网络设置。

Claude 调用 adb_screenshot，获取屏幕图片和图片下方的说明：

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

然后使用图片自身的坐标，通过 adb_tap coords="screenshot" 点击它看到的“网络和互联网”一行。对于没有触摸屏的电视盒子，它会使用 adb_find_and_tap text="Network"，通过遥控器按键将焦点移到该项。

安装到你的 AI 所在的位置

详情、其他配置和检查方法：docs/installation.md。不支持 MCP 的 AI 应用无法使用此服务。

• Home Assistant — 安装 ha-adb-mcp 应用。通过 Home Assistant 的外部地址，可在浏览器聊天中访问它。

• Claude Desktop（Windows、macOS）— 从最新版本下载 .mcpb 文件并将其拖入 Claude Desktop 窗口，或在“设置”→“扩展”→“高级设置”→“安装扩展…”中选择该文件（双击也可以，除非文件被归档工具打开）；Claude Desktop 会显示一个简短表单并安装它。无需 Node.js。也可使用 JSON 配置：docs/installation.md。

• Claude Code：

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

• 你电脑上的其他 MCP 客户端 — 服务命令为 npx -y brickproof-adb。

• 不使用 Home Assistant 的浏览器聊天 — 需要一台家中常开并运行 brickproof-adb serve 的电脑，且该电脑需有可公开访问的 HTTPS 地址：docs/installation.md。

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

首次运行

1. 在设备上开启调试。 Android TV、Google TV、Fire TV 和手机通常会将其隐藏在“开发者选项”中；在设置的“关于”界面连续点按版本号七次即可显示该选项。然后：使用数据线时开启 USB 调试；许多电视盒子可开启网络调试或 ADB 调试；Android 11 或更高版本的手机可开启无线调试。
2. 告诉助手“查找我的电视”（或手机）。它会搜索网络并建议要连接的设备；通过数据线连接的手机会自动显示。
3. 在设备屏幕上确认允许调试的提示，并勾选“始终允许”。通过 Wi-Fi 连接的手机则会要求输入屏幕上显示的配对码。

无需配置的默认设置：文件会从“下载”文件夹接收或发送，已连接的设备会被记住，adb 会自动查找（或者运行 brickproof-adb get-adb 下载）。

要求

• Node.js 22.17 或更高版本 — Claude Desktop 扩展、Home Assistant 和 Docker 配置除外。
• adb（Android SDK Platform-Tools）：会自动从 Android Studio、WinGet、Homebrew 或系统的安装位置查找，也可以使用 brickproof-adb get-adb 下载。Docker 和 Home Assistant 自带 adb。
• 已开启调试的设备，通过 USB 或网络连接。

连接

通过 stdio（Claude Desktop、Claude Code）无需连接：客户端会启动服务。通过 HTTP（brickproof-adb serve）连接时，令牌可放在路径中或请求头中：

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

首次启动时会生成令牌；运行 brickproof-adb token 可再次查看，运行 brickproof-adb token --new 可更换令牌。详见 docs/security.md。

工具

共 18 个工具。语义、拒绝和时限：docs/tools.md；屏幕几何信息和输入：docs/screen-and-input.md。

• adb_devices — 已连接和已记住的设备；discover=true 会搜索网络
• adb_connect — 连接网络设备，格式为 ip 或 ip:port；会记住该设备，供下次启动时使用
• adb_disconnect — 断开一个网络设备（并将其忘记），或断开所有设备
• adb_pair — 通过 Wireless debugging 与 Android 11+ 设备配对
• adb_shell — 执行任意 shell 命令；除非设置了 allow_shell，否则不可用
• adb_logcat — 最近的日志行，在设备上进行筛选
• adb_screenshot — 获取屏幕 JPEG 图像，并提供点击所用的缩放比例
• adb_ui_dump — 获取屏幕上的元素及其点击坐标
• adb_tap — 点击某个点，坐标可使用屏幕坐标或截图坐标
• adb_swipe — 滑动或长按
• adb_key — 按下某个按键（HOME、BACK、DPAD_CENTER…）
• adb_text — 在当前聚焦的字段中输入文本，通过 ADBKeyBoard 输入 Unicode
• adb_find_and_tap — 按元素标签查找并激活元素
• adb_install — 安装 APK、分割包集合或 .apks/.xapk/.apkm 捆绑包；默认执行试运行；未提供路径时，会列出可安装的内容
• adb_uninstall — 按软件包名称移除应用
• adb_app — 带有防护措施、快照和回滚功能的软件包操作
• adb_push — 将文件复制到设备
• adb_pull — 从设备复制文件

安全

了解哪些措施能保护你的设备，哪些不能：docs/safety.md。简而言之：默认执行试运行、从设备读取受保护集合、对运行中的服务设置网络防护、批次之间使用账户金丝雀检查、创建快照并支持一次调用回滚；adb_shell 和卸载功能默认关闭，需手动启用。没有任何工具会更改这些开关；你可以使用 brickproof-adb set 或在应用设置中进行更改。

限制

• ADB 不是沙盒。启用 allow_shell 后，adb_shell 可以执行设备 shell 用户能够执行的任何操作，不受任何防护措施限制。
• 搜索仅能发现同一网络上的设备：访客网络、Wi-Fi 客户端隔离或不同 VLAN 会导致设备无法被发现。在 Docker 和 Home Assistant 中，只能发现端口 5555 上的电视盒子；手机需使用屏幕上显示的地址连接。
• 工具列表会按聊天缓存；更新后请开始新聊天。
• 处于休眠状态的设备截图会显示为黑屏，且回答会显示 screen: Asleep；执行 adb_key key=WAKEUP 可唤醒设备，随后 HDMI-CEC 可能会打开电视。
• 受 FLAG_SECURE 保护的内容（流媒体播放器、银行应用）会显示为黑屏。
• 快照保存在创建快照的机器上：必须在进行更改的机器上执行回滚。
• Docker 中的 USB 设备仅在 Linux 主机上可用。

许可证

MIT