Android ADB MCP Server

Android ADB MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 助手通过 Android Debug Bridge（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 时，将按以下规则解析路径：

• 绝对路径保持不变
• 以 ~ 开头的路径将展开为用户的主目录
• 相对路径将相对于用户的主目录解析

这样可以确保截图保存到 MCP 服务具有写入权限的位置。

🔍 故障排除

常见问题

1. “ADB is not available”错误

   • 确保已安装 ADB，且其位于系统 PATH 中
   • 在终端中运行 adb version 进行验证

2. “No Android devices connected”错误

   • 使用 adb devices 检查设备是否已正确连接
   • 确保设备已启用 USB 调试
   • 尝试依次运行 adb kill-server 和 adb start-server 重启 ADB

3. “Multiple devices connected”错误

   • 在工具调用中指定 device_id 参数
   • 使用 adb_devices 工具获取可用设备列表

4. 无法将截图复制到剪贴板

   • 确保已安装所需的平台专用工具

🔧 其他安装方式

选项 1：从 npm 安装

# Install globally
npm install -g @landicefu/android-adb-mcp-server

# Or install locally in your project
npm install @landicefu/android-adb-mcp-server

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

1. 克隆仓库：

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

2. 安装依赖并构建：

   npm install
   npm run build
   

3. 使用直接路径进行配置：

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

📄 许可证

本项目采用 ISC 许可证授权，详情请参阅 LICENSE 文件。

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 发起 Pull Request