adbmcp

用手机当 AI 的设备遥控器 —— 把 Android 手机变成 MCP 服务器，让 Claude / Cursor / RikkaHub / WorkBuddy 等任意 AI 客户端通过自然语言直接操作你的设备。

你在 RikkaHub 里说：「现在有几台设备在线？分别什么系统？」
                    ↓
              AI 调用 MCP 工具
                    ↓
        手机 Termux (termux-native-mcp :8081)
                    ↓  adb shell
         设备 .39 / .133 (Buildroot Linux)

为什么是手机 Termux 方案

早期方案是让 PC 跑 mobile-mcp（基于无障碍树的 Android 自动化）。实测发现设备是 Buildroot Linux（无 getprop、无 wm），无障碍树那套完全无效，只有纯 adb shell 路线能操作。

Related MCP server: android-adb-mcp

特性

• 一键启动 —— Termux 里敲 adbmcp 即可，只启动 MCP 并输出接入信息

• 不打扰设备 —— 启动时不会主动连接任何设备；守护等设备接入后才开始工作

• 局域网直连 —— 任意 AI 客户端通过 http://<手机IP>:8081/mcp 接入，无需 PC 中转

• 固定 Token —— 跨设备迁移时 AI 客户端配置无需改动

• 延后守护 —— 后台守护先等待设备接入，检测到设备后才开始维持连接

• 双端守护 —— 手机端守护 MCP 进程与设备连接，PC 端守护 adb 隧道，断线自动自愈

• 84 个工具 —— 基于 termux-mcp v0.15.0，含 shell 执行、文件读写、截图、通知等

• 危险命令拦截 —— 服务端识别高危命令并要求显式确认

快速开始

1. 手机装 Termux

从 F-Droid 或 GitHub 安装（不要用 Play 商店的旧版）。首次打开等它初始化完。

2. 安装

方式 A · PyPI（推荐，无需传文件）

pip install termux-adbmcp
adbmcp

首次运行 adbmcp 会自动完成部署：复制脚本到 ~/bin、安装依赖（android-tools + termux-mcp）、打上游补丁。之后直接敲 adbmcp 即可。

方式 B · 一行脚本

curl -fsSL https://cdn.jsdelivr.net/gh/wu737/adbmcp@main/install/bootstrap.sh | bash

方式 C · 手动部署

把 install/install-adbmcp.sh 与 scripts/ 下的文件传到手机 Termux（~/adbmcp/），然后：

cd ~/adbmcp
bash install/install-adbmcp.sh

脚本自动完成：装依赖（android-tools + termux-mcp）→ 部署脚本 → 建设备清单 → 启动自检 → 扫描网段找可连接设备。

3. 填设备清单

编辑 ~/mcp-servers/adbmcp/devices.txt：

192.168.43.1:5555    设备热点网关
192.168.110.39:5555  设备 - Buildroot/wise

adbmcp restart

4. 接入 AI 客户端

adbmcp config 直接打印可粘贴的配置：

{
  "mcpServers": {
    "adbmcp": {
      "type": "streamableHttp",
      "url": "http://192.168.110.13:8081/mcp",
      "timeout": 120000,
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

RikkaHub 专用格式见 examples/rikkahub-mcp-import.json。

5. 用起来

在 AI 对话框里直接说人话，AI 会自己判断要不要调工具：

现在 adb 里能连到哪些设备？分别是什么系统？
设备 192.168.110.39 上有哪些应用目录？
用 system_info 看一下手机 CPU 和内存

命令一览

自动打补丁 —— termux-mcp v0.15.0 未实现 MCP 规范要求的 notifications/* 通知方法，客户端（尤其 RikkaHub）会因此报「Error while sending message」。 adbmcp 每次启动都会自动检查并打上补丁（见 scripts/patch_cancelled.py），pip 升级后同样自动重打。

依赖

目录结构

install/install-adbmcp.sh   一键安装
scripts/
  adbmcp                    主脚本（PATH 内，直接敲 adbmcp）
  device_watchdog.sh        守护：MCP 进程 + 设备连接
  device_setup.sh           手动连接设备
  scan_device.py            网段扫描
  boot_mcp.sh               开机自启入口
  patch_cancelled.py        上游补丁（补齐 notifications/* 方法）
docs/                       详细文档
examples/                   各客户端配置示例

部署到手机后：

~/bin/adbmcp                   ← 主脚本
~/mcp-servers/adbmcp/           ← 设备清单、日志、配置
~/.termux/boot/boot_mcp.sh     ← 开机自启

文档

关于同名项目

有一个也叫 adbmcp 的项目：yhuangsh/adbmcp（npm 包 @yhuangsh/adbmcp）。 两者不是同一个东西，名字相同纯属巧合，可以并存：

实测证据：对方的 Android 专属工具在设备上全部 not found（设备是 Buildroot，无 Android framework）。 详见 对比文档。

安全须知

⚠️ 本项目默认使用固定 Token，且仓库中公开了默认值。

• 服务绑定 0.0.0.0 时，服务端强制要求 Token（termux-native-mcp 的 _check_startup_guards 逻辑），无 Token 会直接拒绝启动

• 完全免鉴权只能绑 127.0.0.1（adbmcp local），那样局域网无法直连

• 默认 Token 是公开的。若你的网络环境不完全可信，请改用随机值：

  export ADBMCP_TOKEN=$(head -c 24 /dev/urandom | base64 | tr -d '/+=')
  adbmcp restart

  然后同步更新所有 AI 客户端配置

建议在 RikkaHub / Claude 等客户端侧给高危工具开启「需要审批」：

只读类（read / ls / search / system_info / battery）无需审批。

已知限制

• Termux 被杀 → MCP 进程消失。 守护能扛住「Termux 存活但 MCP 挂掉」，Termux 整体被杀需重开 App（装 Termux:Boot 可自动拉起）

• 无线调试会因息屏断开。 实测手机多次转 offline。对策：termux-wake-lock、关闭电池优化、或改用 USB

• Termux 无 ip 命令权限，/proc/net/fib_trie 也被 Android 11+ 收紧 → IP 探测改用 Python socket

• Termux 版 adb 无 adb mdns → 设备 IP 靠手填或 adbmcp scan 扫描

• run 对含 ; 的复合命令可能返回空 → 拆成单条分别调用

License

MIT