MCP 服务器

Android ADB MCP Server

一个模型上下文协议服务器，它使 AI 助手能够通过 ADB 与 Android 设备交互，从而实现自动化设备管理、应用安装、文件传输和屏幕截图捕获。

README

Android ADB MCP 服务器

一个模型上下文协议 (MCP) 服务器，它使 AI 助手能够通过 Android 调试桥 (ADB) 与 Android 设备交互。该服务器弥合了 AI 功能和 Android 设备管理之间的差距，从而可以无缝地自动化 Android 开发和测试操作。

⚙️ 快速设置

将服务器添加到您的 MCP 配置文件：

{
  "mcpServers": {
    "android-adb": {
      "command": "npx",
      "args": ["-y", "@landicefu/android-adb-mcp-server"],
      "env": {},
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

配置位置

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cline/Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json (macOS)
对于 Windows/Linux，请检查等效的应用程序支持目录

配置完成后，重新启动您的 AI 助手以加载新的服务器配置。

📋 前提条件

ADB (Android Debug Bridge) 必须已安装并且在您的系统 PATH 中可用
- 在 Windows、macOS 或 Linux 上安装 ADB
- 通过在终端中运行 adb version 来验证安装
对于剪贴板功能：
- macOS: osascript (内置)
- Windows: PowerShell (内置)
- Linux: xclip (通过 apt-get install xclip 或等效命令安装)
Node.js 16.x 或更高版本

🚀 功能

连接和管理多个 Android 设备
在 Android 设备上执行 shell 命令
安装和卸载应用程序
在本地系统和 Android 设备之间推送和拉取文件
在 Android 设备上启动应用程序
截取屏幕截图并将其本地保存或复制到剪贴板
连接多个设备时进行智能设备选择

🛠️ 可用工具

工具	描述	必需参数	可选参数
`adb_devices`	列出连接的设备	无	无
`adb_shell`	执行 shell 命令	`command`	`device_id`
`adb_install`	安装 APK 文件	`path`	`device_id`
`adb_uninstall`	卸载应用程序	`package_name`	`device_id`
`adb_list_packages`	列出已安装的软件包	无	`device_id`, `filter`
`adb_pull`	从设备拉取文件	`remote_path`, `local_path`	`device_id`
`adb_push`	将文件推送到设备	`local_path`, `remote_path`	`device_id`
`launch_app`	启动应用程序	`package_name`	`device_id`
`take_screenshot_and_save`	截取并保存屏幕截图	`output_path`	`device_id`, `format`
`take_screenshot_and_copy_to_clipboard`	将屏幕截图截取到剪贴板	无	`device_id`, `format`

设备管理

服务器智能地处理设备选择：

如果仅连接了一个设备，它将自动使用
如果连接了多个设备，则必须指定 device_id 参数
如果未连接任何设备，则将返回错误

屏幕截图路径解析

指定用于保存屏幕截图的 output_path 时，路径解析如下：

绝对路径按原样使用
以 ~ 开头的路径扩展到用户的 home 目录
相对路径相对于用户的 home 目录解析

这确保了屏幕截图保存到 MCP 服务器具有写入权限的位置。

🔍 故障排除

常见问题

“ADB is not available” 错误
- 确保已安装 ADB 并且在您的系统 PATH 中
- 通过在终端中运行 adb version 来验证
“No Android devices connected” 错误
- 使用 adb devices 检查您的设备是否已正确连接
- 确保在您的设备上启用了 USB 调试
- 尝试使用 adb kill-server 重新启动 ADB，然后使用 adb start-server
“Multiple devices connected” 错误
- 在您的工具调用中指定 device_id 参数
- 使用 adb_devices 工具获取可用设备列表
屏幕截图到剪贴板不起作用
- 确保已安装所需的平台特定工具

🔧 替代安装方法

选项 1：从 npm 安装

# 全局安装
npm install -g @landicefu/android-adb-mcp-server

# 或者在您的项目中本地安装
npm install @landicefu/android-adb-mcp-server

选项 2：从源代码手动安装

克隆存储库：

git clone https://github.com/landicefu/android-adb-mcp-server.git
cd android-adb-mcp-server

安装依赖项并构建：
```
npm install
npm run build
```

使用直接路径配置：

{
  "mcpServers": {
    "android-adb": {
      "command": "node",
      "args": ["/path/to/android-adb-mcp-server/build/index.js"],
      "env": {},
      "disabled": false,
      "alwaysAllow": []
    }
  }
}