Metadata-Version: 2.5
Name: termux-adbmcp
Version: 0.2.0
Summary: Turn an Android phone (Termux) into an MCP server so AI clients can drive adb devices by natural language
Project-URL: Homepage, https://github.com/wu737/adbmcp
Project-URL: Repository, https://github.com/wu737/adbmcp
Project-URL: Issues, https://github.com/wu737/adbmcp/issues
Project-URL: Changelog, https://github.com/wu737/adbmcp/releases
Author: wu737
License: MIT License
        
        Copyright (c) 2026 adbmcp contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: adb,android,automation,device-control,iot,mcp,model-context-protocol,shell-automation,termux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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` 路线能操作。

| 维度 | 手机 Termux 宿主角 | PC 端 mobile-mcp |
|---|---|---|
| 设备兼容性 | ✅ 纯 adb shell | ❌ 依赖无障碍树，非 Android 设备无效 |
| 设备可达性 | ✅ 手机连设备热点即可 | ❌ PC 必须与设备同网段 |
| 现场部署 | ✅ 手机 + 设备，无需 PC | ❌ 需 PC 参与 |
| 断线恢复 | ✅ 双端守护自动重连 | ❌ 仅单端 |

---

## 特性

- **一键启动** —— 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（推荐，无需传文件）**

```bash
pip install termux-adbmcp
adbmcp
```

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

**方式 B · 一行脚本**

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

**方式 C · 手动部署**

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

```bash
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
```

```bash
adbmcp restart
```

### 4. 接入 AI 客户端

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

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

RikkaHub 专用格式见 [`examples/rikkahub-mcp-import.json`](examples/rikkahub-mcp-import.json)。

### 5. 用起来

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

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

---

## 命令一览

| 命令 | 作用 |
|---|---|
| `adbmcp` | 启动 + 打印接入信息（默认） |
| `adbmcp status` | 查看 MCP / 守护 / adb 设备状态 |
| `adbmcp config` | 打印可粘贴的 AI 客户端配置 |
| `adbmcp connect` | 手动连接设备清单里的设备 |
| `adbmcp token` | 显示当前固定 token |
| `adbmcp scan [网段]` | 扫描网段找出所有开 5555 的设备 |
| `adbmcp lan` / `adbmcp local` | 切换局域网模式（+token）/ 仅本机模式（免鉴权） |
| `adbmcp restart` / `stop` | 重启 / 停止 |

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

---

## 依赖

| 依赖 | 版本 | 安装方式 |
|---|---|---|
| Termux | ≥ 0.118 | F-Droid / GitHub |
| android-tools (adb) | 37.0.0 | `pkg install android-tools` |
| python | 3.14.x | `pkg install python` |
| [termux-mcp](https://pypi.org/project/termux-mcp/) | 0.15.0 | `pip install termux-mcp==0.15.0` |
| Termux:Boot | — | 单独 APK（可选，用于开机自启） |

---

## 目录结构

```
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     ← 开机自启
```

---

## 文档

| 文档 | 内容 |
|---|---|
| [快速开始](docs/快速开始.md) | 完整命令与机制说明 |
| [设备接入](docs/设备接入.md) | 设备识别、协议限制、故障排查 |
| [RikkaHub 接入](docs/RikkaHub-接入.md) | RikkaHub 两层配置（全局 MCP + 助手绑定）|
| [RikkaHub 对话使用](docs/RikkaHub-对话使用.md) | 实测可用的提问示例、路径权限边界 |
| [RikkaHub 工具调用排查](docs/RikkaHub-工具调用排查.md) | 「当前模型未开启工具调用」根因（源码级）|
| [迁移指南](docs/迁移指南.md) | 换新手机部署 |
| [诊断记录](docs/诊断记录-工具不可用.md) | 完整排查过程留档 |
| [对比 yhuangsh/adbmcp](docs/对比-yhuangsh-adbmcp.md) | 同名项目的区别（宿主位置 / 目标设备不同）|
| [排障 notifications/cancelled](docs/排障-notifications-cancelled.md) | RikkaHub 报「Error while sending message」的根因 |

---

## 关于同名项目

有一个也叫 `adbmcp` 的项目：[yhuangsh/adbmcp](https://github.com/yhuangsh/adbmcp)（npm 包 `@yhuangsh/adbmcp`）。
**两者不是同一个东西，名字相同纯属巧合**，可以并存：

| | yhuangsh/adbmcp | 本项目 |
|---|---|---|
| 宿主 | PC / 任意装 Node≥20 的机器 | **手机 Termux** |
| 目标设备 | **Android 手机** | **Buildroot Linux 设备** |
| 实现 | TypeScript 1300+ 行自研，37 工具 | Bash 复用 `termux-mcp`，84 工具 |
| 特色 | Android 深度集成（uiautomator/logcat/pm/input）、npm 分发、完整测试与 CI | 设备运维、手机即网关、零 Node 依赖、Token 固定 |

实测证据：对方的 Android 专属工具在设备上全部 `not found`（设备是 Buildroot，无 Android framework）。
详见 [对比文档](docs/对比-yhuangsh-adbmcp.md)。

---

## 安全须知

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

- 服务绑定 `0.0.0.0` 时，**服务端强制要求 Token**（`termux-native-mcp` 的 `_check_startup_guards` 逻辑），无 Token 会直接拒绝启动
- 完全免鉴权只能绑 `127.0.0.1`（`adbmcp local`），那样局域网无法直连
- **默认 Token 是公开的**。若你的网络环境不完全可信，请改用随机值：
  ```bash
  export ADBMCP_TOKEN=$(head -c 24 /dev/urandom | base64 | tr -d '/+=')
  adbmcp restart
  ```
  然后同步更新所有 AI 客户端配置

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

| 工具 | 风险 |
|---|---|
| `run` | ⚠️ 执行任意 shell —— 能操作设备、读写手机文件 |
| `write` / `delete` | 改 / 删文件（软删除，落在 `~/termuxGPT/trash/`）|
| `process_kill` | 杀进程 |
| `sms_send` | 发短信 |
| `camera_photo` | 拍照 |

只读类（`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
