内容
# ADB 模型上下文协议（MCP）服务器
一款高性能的模型上下文协议（MCP）服务器，暴露了 Android 调试桥（ADB）的功能。这使得 AI 助手（例如 Claude Desktop 或其他兼容 MCP 的客户端）可以直接与 Android 设备（模拟器或物理硬件）交互和控制。
## 功能特点
- **零配置（自动下载）**：服务器启动时，会自动检查 ADB 是否可用。如果 ADB 缺失，服务器会自动检测操作系统（Windows、macOS 或 Linux），下载官方的 Google 平台工具，解压到本地，并立即开始使用。
- **丰富的输出检查**：直接从设备捕获截图，并将它们作为高质量的 PNG 内容块**内联**传递给 LLM。
- **完整的 26 种工具套件**：完全控制 shell 脚本、文件传输、按键输入事件、应用程序执行、诊断信息和设备控制。
---
## 🚀 安装与配置
### 前置条件
确保您已安装 [Node.js（v22+）](https://nodejs.org/)。
### 1. 克隆与安装依赖
克隆存储库并安装软件包：
```bash
git clone https://github.com/RedZONERROR/AdbMCP.git
cd AdbMCP
npm install
```
---
## ⚙️ 配置 Claude Desktop
要将 ADB MCP 服务器添加到 Claude Desktop，请编辑您的配置文件：
- **Windows**： `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**： `~/Library/Application Support/Claude/claude_desktop_config.json`
在 `mcpServers` 对象中添加服务器定义：
```json
{
"mcpServers": {
"adb-mcp": {
"command": "node",
"args": [
"/absolute/path/to/adb-mcp/index.js"
]
}
}
}
```
将 `/absolute/path/to/adb-mcp/index.js` 替换为您的计算机上的存储库的实际路径：
- **Windows 示例**： `C:/path/to/adb-mcp/index.js` *(注意：在配置文件中使用正斜杠 `/` 以防止转义错误)*。
- **macOS 示例**： `/Users/YOUR_USERNAME/GitHub/adb-mcp/index.js`
- **Linux 示例**： `/home/YOUR_USERNAME/GitHub/adb-mcp/index.js`
---
## 🛠️ 暴露的工具列表
服务器注册了 26 个不同的工具：
### 设备发现与控制
- `adb_list_devices`：列出所有连接的设备或模拟器及其型号和状态。
- `adb_device_info`：检索详细的硬件规格、电池电量、分辨率和操作系统属性。
- `adb_reboot`：重启设备（正常、引导加载程序或恢复模式）。
### Shell 执行与应用管理
- `adb_shell`：在设备上执行 shell 命令（例如 `pm list packages`、`df -h`）。
- `adb_run_script`：通过将复杂的多行 shell 脚本上传到设备并运行它们，以确保标准行结束符兼容性。
- `adb_install`：从主机安装本地 `.apk` 文件到设备。
- `adb_uninstall`：卸载应用程序包。
- `adb_list_packages`：列出设备上安装的软件包（可以根据查询或仅限第三方软件包进行筛选）。
- `adb_start_app`：使用软件包名称（和可选活动）启动应用程序。
- `adb_stop_app`：强制停止应用程序包。
- `adb_clear_app_data`：清除软件包的用户数据和缓存（`pm clear`）。
- `adb_grant_permission`：授予或撤销运行时权限（例如 `CAMERA`、`WRITE_EXTERNAL_STORAGE`）。
### 用户交互与输入模拟
- `adb_screenshot`：捕获设备屏幕并将其作为内联图像（PNG base64）返回。
- `adb_keyevent`：发送按键事件（主页、返回、电源、音量等）。
- `adb_input_text`：在当前活动输入字段中输入文本。
- `adb_tap`：在特定 `(x, y)` 坐标处点击。
- `adb_swipe`：从 `(x1, y1)` 滑动到 `(x2, y2)` 并持续一段时间。
- `adb_current_activity`：检索当前聚焦活动的软件包和类名。
### 设备文件系统管理
- `adb_file_push`：将主机上的文件或目录上传到设备。
- `adb_file_pull`：将设备上的文件或目录下载到主机。
- `adb_device_ls`：列出设备文件夹中的文件和文件夹。
- `adb_device_rm`：删除设备上的文件或目录。
- `adb_device_mv`：在设备上移动或重命名文件或目录。
- `adb_device_cp`：在设备上复制文件或目录。
- `adb_device_mkdir`：在设备上创建新目录。
### 日志
- `adb_logcat`：使用可选筛选器转储 logcat 中的近期日志。
---
## 💡 手动测试
您可以通过命令行直接运行服务器以检查错误或验证 ADB 解析：
```bash
npm start
```
*注意：由于它运行在 stdio 传输上，它将等待 JSON-RPC 输入。要退出，请按 `Ctrl+C`。*
要运行带有视觉控制台输出的测试，请参阅 `test.js`。
