ADB MCP Server

这是一个通过ADB与Android设备交互的MCP（模型上下文协议）服务器。这个基于TypeScript的工具提供了一个连接AI模型和Android设备功能的桥梁。

特性

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

预备条件

• Node.js（推荐使用v16或更高版本，已测试过Node.js v16、v18和v20）
• 已安装并添加到PATH中的ADB（Android调试桥）
• 通过USB或网络连接的Android设备或模拟器，并且启用了USB调试
• 访问设备的权限（在设备上接受调试授权）

安装

通过Smithery安装

要通过Smithery自动安装ADB Android设备服务器：

npx -y @smithery/cli install @srmorete/adb-mcp --client claude

手动安装

# 克隆仓库
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 Server connected and ready

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

可用工具

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

📱 设备管理

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

📦 应用管理

• adb_install - 使用本地文件路径安装APK文件
• adb_package_manager - 执行包管理器（pm）命令 - 列出包，授予/撤销权限，管理应用
• adb_activity_manager - 执行活动管理器（am）命令 - 启动活动，广播意图，控制应用行为

📋 日志记录

• 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及以上版本
• 包括Cursor IDE中的Claude在内的MCP客户端
• 在macOS上构建，但应该可以在任何POSIX兼容系统（如Linux等）上运行。
• 尚未在Windows上尝试，但可能可以运行。

贡献

• 欢迎贡献！提交一个Pull Request。
• 对于重大更改，请先打开一个问题进行讨论。
• 当然，你也可以分叉它
• 注意： 此项目是vibe-coded编写的，如果你发现一些奇怪的东西……现在你知道了 😄

许可证

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

致谢

• 使用模型上下文协议 (MCP)构建