Android ADB MCP Server 是一个模型上下文协议（MCP）服务端，用于让 AI 助手安全地通过 ADB 控制 Android 设备。它面向需要让 AI 助手直接操作或读取 Android 设备状态的开发者与自动化场景。
用途
让具备 MCP 能力的 AI 助手（如 Claude、OpenCode，以及通过 Copilot/代理集成使用 MCP 的 VS Code）通过 ADB 与 Android 设备交互。需要注意的是，Claude 和 OpenCode 是 AI 助手，VS Code 本身不是 AI，而是承载 AI 助手并作为 MCP 客户端的代码编辑器；该服务端可与任何支持 MCP 的客户端配合使用。
主要能力
服务端暴露以下工具：读取 logcat、检查当前 UI 层级、列出已安装的软件包，以及执行受限的 shell 命令。所有命令都受允许列表约束，以降低任意命令执行的风险。
安全设计
- Shell 允许列表：adb_execute_shell 只接受前缀被授权的命令（getprop、dumpsys、pm list）。其他命令会被拒绝并返回描述性错误。命令链（&&、||、;、|）和注入用元字符也会被阻止。
- 不使用 root：不请求超级用户权限，仅使用标准 ADB API。
- 命令通过 execFile 执行（不经过中间 shell），避免元字符注入。
- 安全逻辑位于 src/adb/security.ts，在扩大权限前应先审阅。
前置条件
- Node.js v18+（已测试至 Node.js 26）。
- 已安装 ADB 且可通过系统 PATH 访问（adb version 必须可用），或通过 ADB_PATH / ANDROID_HOME / 标准 SDK 路径定位。
- Android 设备已开启 USB 调试（开发者选项 → USB 调试）。
安装与使用
构建会在 dist/ 文件夹中生成编译后的代码。注意：dist/ 是本地生成，不提交到仓库，必须先运行 npm run build 再配置 MCP 客户端，否则服务端无法启动。
快速开始（已发布到 npm）：可跳过克隆和构建，服务端已发布为 @neem2004/android-mcp-server 并包含编译后的 dist/。直接运行 npx -y @neem2004/android-mcp-server。绝对路径形式适用于本地克隆（将 YOUR_PATH_TO 替换为实际位置）。
各 MCP 客户端的配置文件与格式不同，常见配置如下：
- OpenCode：文件为项目根目录的 opencode.json，或全局的 ~/.config/opencode/opencode.json。本地克隆替代方案："command": ["node", "YOUR_PATH_TO/android-mcp-server/dist/index.js"]。
- Claude：文件为 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。本地克隆替代方案："command": "node"，"args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"]。
- VS Code：文件为工作区中的 .vscode/mcp.json（或通过 MCP: Open User Configuration 命令）。VS Code 使用 servers 作为顶层键（不是 mcpServers）。
开发提示：可用 tsx 直接运行 TypeScript，将参数替换为 src/index.ts 并使用 npx tsx 作为命令；但为可靠性，建议使用编译后的构建。
ADB 配置
如果尚未安装 ADB：
- Windows：下载官方 platform-tools 并将其文件夹添加到系统 PATH。
- macOS / Linux：通过包管理器安装（例如 brew install android-platform-tools、apt install adb）。 设备应显示为 device（而非 unauthorized / offline）。服务端会依次使用 ADB_PATH、ANDROID_HOME / ANDROID_SDK_ROOT、标准 SDK 路径，最后回退到 PATH 中的 adb。
项目与支持
该项目 100% 开源并独立维护。如对团队自动化流程有帮助，可通过 GitHub Sponsors 支持 Neem2004；企业赞助用于资助新工具、安全加固和优先支持。
