ADB MCP 服务器

一个通过 ADB 与 Android 设备交互的 MCP（Model Context Protocol）服务器。这个基于 TypeScript 的工具提供了 AI 模型与 Android 设备功能之间的桥梁。

功能

• 📱 设备管理 - 列出并操作连接的 Android 设备
• 📦 应用安装 - 将 APK 文件部署到连接的设备
• 📋 日志 - 通过 logcat 访问设备日志
• 🔄 文件传输 - 在设备和主机之间推送和拉取文件
• 📸 UI 交互 - 截图并分析 UI 层次结构
• 🔧 Shell 命令执行 - 在设备上运行自定义命令

先决条件

• Node.js（建议 v16 或更高版本，测试使用 Node.js v16, v18 和 v20）
• 安装并配置好 ADB（Android Debug Bridge）
• 通过 USB 或网络连接的 Android 设备或模拟器，并启用 USB 调试
• 访问设备的权限（在设备上接受调试授权）

安装

# 克隆仓库
git clone https://github.com/srmorete/adb-mcp.git
cd adb-mcp

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

# 运行服务器
npx adb-mcp

配置

ADB 路径配置

服务器使用默认的 ADB 路径。对于自定义 ADB 位置：

export ADB_PATH=/path/to/adb
npx adb-mcp

MCP 配置

添加 ADB MCP 服务器配置：

{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": [
        "adb-mcp"
      ]
    }
  }
}

使用

启动服务器

重要：在使用任何 ADB 工具之前，必须先启动服务器。

使用以下命令启动服务器：

npx adb-mcp

你应该会看到：

[INFO] ADB MCP 服务器已连接并准备好

在使用 ADB 工具时保持此终端窗口打开。

可用工具

所有工具都遵循以下命名约定：

📱 设备管理

• adb_devices - 列出连接的设备
• adb_shell - 在设备上执行 shell 命令

📦 应用管理

• adb_install - 使用本地文件路径安装 APK 文件

📋 日志

• adb_logcat - 查看设备日志（可选过滤）

🔄 文件传输

• adb_pull - 从设备拉取文件
• adb_push - 将文件推送到设备

🔍 UI 交互

• dump_image - 截取当前屏幕截图
• inspect_ui - 获取 XML 格式的 UI 层次结构（对 AI 交互最有用）

故障排除

如果工具无法正常工作：

• 服务器问题：

  • 确保服务器正在运行 (npx adb-mcp)
  • 检查服务器输出中的错误消息
  • 尝试详细日志：LOG_LEVEL=3 npx adb-mcp
  • 终止挂起的进程：
    • ps aux | grep "adb-mcp" | grep -v grep
    • 然后 kill -9 [PID]

• 设备连接：

  • 使用 adb_devices 验证连接
  • 如果出现“未授权”，请在设备上接受调试授权
  • 检查 USB/网络连接
  • 尝试重启 ADB：adb kill-server && adb start-server

• ADB 问题：

  • 验证 ADB 安装：adb version

• 设备设置：

  • 使用模拟器（它是用模拟器构建的），对于真实设备可能需要尝试以下步骤：
    • 确保启用了 USB 调试
    • 对于较新的 Android 版本，启用“USB 调试（安全设置）”
    • 尝试不同的 USB 端口或电缆
    • 或者在 issue 中告诉我

兼容性

• Android 8.0 及以上版本
• 包括 Claude 在 Cursor IDE 中的 MCP 客户端
• 在 macOS 上构建，但应该可以在任何 POSIX 兼容系统（如 Linux 等）上运行。
• 未在 Windows 上进行测试，但可能可以运行。

贡献

• 欢迎贡献！提交 Pull Request。
• 对于重大更改，请先开一个 issue 进行讨论。
• 当然也可以 fork 项目
• 注意： 该项目是“vibe-coded”的，如果你发现一些奇怪的东西……现在你知道了 🙂

许可

该项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。

致谢

• 使用 Model Context Protocol (MCP) 构建