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）并将其添加到 PATH 中
• 通过 USB 或网络连接的 Android 设备或模拟器，并启用了 USB 调试
• 访问设备的权限（在设备上接受调试授权）

安装

# Clone the repository
git clone https://github.com/srmorete/adb-mcp.git
cd adb-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run the server
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 Server connected and ready

在使用 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 端口或电缆
    • 或者在问题中告诉我

兼容性

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

贡献

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

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 使用 Model Context Protocol (MCP) 构建