JinDaGe - mcp_adb MCP Details

article

README

🚀 ADB MCP 服务器（Python 版）

这是一个用 Python 编写的 MCP（模型上下文协议）服务器，它允许 Claude 直接通过 Android 调试桥（ADB）与安卓设备进行通信。

🚀 主要特性

设备管理：列出已连接的设备
命令执行：在安卓设备上执行 shell 命令
安装/卸载应用：管理设备上的应用程序
日志捕获：访问安卓设备的 logcat 日志
屏幕截图：捕获设备屏幕
文件传输：推送/拉取文件
输入模拟：模拟触摸、滑动和输入操作
应用列表：查看已安装的应用
系统信息：获取电池、版本、型号和内存等系统信息

📋 前置要求

Python 3.10 及以上版本
uv（Python 包管理器）
ADB（Android Debug Bridge），安装路径为 C:\Users\Cristiano\Programação\ADB\
安卓设备，并已开启 USB 调试模式
Claude Desktop，支持 MCP 协议

📦 安装指南

1. 安装 uv（如果尚未安装）

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

# 或者从官方网站下载：https://github.com/astral-sh/uv

2. 创建并配置项目

# 创建目录
mkdir adb-mcp-server
cd adb-mcp-server

# 保存文件（main.py 和 pyproject.toml）
# 之后执行：

# 安装依赖项
uv sync

# 测试是否正常工作
uv run python main.py

3. 文件结构

adb-mcp-server/
├── main.py              # 服务器主代码
├── pyproject.toml        # 项目配置文件
├── README.md            # 本文件
└── .venv/              # 虚拟环境（由 uv 创建）

⚙️ 在 Claude Desktop 中的配置

将以下配置添加到 Claude Desktop 的配置文件中：

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adb": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\caminho\\para\\adb-mcp-server",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

实际路径示例：

{
  "mcpServers": {
    "adb": {
      "command": "uv",
      "args": [
        "--directory", 
        "C:\\Users\\Cristiano\\Documents\\adb-mcp-server",
        "run",
        "python", 
        "main.py"
      ]
    }
  }
}

📱 准备安卓设备

启用开发者选项：
- 进入设置 > 关于手机
- 点击“版本号”7 次
启用 USB 调试：
- 设置 > 开发者选项
- 开启“USB 调试”
通过 USB 连接设备：
- 将设备连接到电脑
- 在安卓设备上接受授权提示
测试连接：

# 在你的 ADB 目录下
cd "C:\Users\Cristiano\Programação\ADB"
.\adb.exe devices

💻 使用示例

基础用法

"列出已连接的安卓设备"
"我的手机上安装了哪些应用？"
"截取屏幕并保存到 C:\Screenshots\tela.png"
"显示我的手机电池信息"

高级用法

自动化与控制

"点击我的手机坐标 500, 800 处"
"在我的手机上输入 '你好，世界'"
"从坐标 300,500 滑动到 300,200"
"按下主页按钮（按键事件 3）"

开发与调试

"在我的手机上执行 'getprop ro.build.version.release' 命令"
"显示最近 50 条包含 'Error' 过滤条件的系统日志"
"安装 C:\Downloads\meuapp.apk 应用"
"卸载 com.exemplo.meuapp 应用"

文件传输

"将文件 C:\Downloads\foto.jpg 发送到 /sdcard/Pictures/"
"将文件 /sdcard/Download/documento.pdf 下载到 C:\Documentos\"

🔧 可用命令

| 命令 | 描述 | 使用示例 | |------|------|----------| | adb_devices | 列出设备 | "哪些设备已连接？" | | adb_shell | 执行 shell 命令 | "在手机上执行 'ls /sdcard/'" | | adb_install | 安装 APK | "安装 C:\app.apk 应用" | | adb_uninstall | 卸载应用 | "卸载 com.example.app 应用" | | adb_logcat | 捕获日志 | "显示包含 'Error' 过滤条件的日志" | | adb_screenshot | 截取屏幕 | "截取屏幕并保存到 C:\tela.png" | | adb_push | 发送文件 | "将文件.txt 发送到 /sdcard/" | | adb_pull | 拉取文件 | "将 /sdcard/foto.jpg 文件下载到 C:" | | adb_input | 模拟输入 | "点击坐标 100, 200" | | adb_apps | 列出应用 | "我安装了哪些应用？" | | adb_info | 系统信息 | "显示电池信息" |

🔍 问题解决

错误：“未找到 ADB”

# 检查代码中的路径
# 编辑 main.py 中的 ADB_PATH 变量
ADB_PATH = r"C:\Users\Cristiano\Programação\ADB\adb.exe"

错误：“未找到设备”

# 手动测试
cd "C:\Users\Cristiano\Programação\ADB"
.\adb.exe devices

# 如果未显示设备：
# 1. 重新连接 USB 线
# 2. 撤销 USB 授权并重新授权
# 3. 安装设备制造商的 USB 驱动程序

错误：“权限被拒绝”

某些命令需要 root 权限
检查应用是否具有必要的权限
某些命令仅在开发者模式下可用

测试服务器

# 在项目目录下
uv run python main.py

# 如果没有错误消息，则服务器正常运行
# 按 Ctrl+C 停止

🚀 uv 的常用命令

# 安装/更新依赖项
uv sync

# 运行服务器
uv run python main.py

# 添加新的依赖项
uv add 库名称

# 更新所有依赖项
uv sync --upgrade

# 查看依赖项
uv tree

🔐 安全注意事项

⚠️ 重要提示

此服务器以用户权限执行 ADB 命令。

仅在自己的设备上使用。

谨慎执行未知的 shell 命令。

保持 ADB 为最新版本。

如果连接多个设备，设备将按 ID 进行隔离。

📈 未来改进

[ ] 支持同时连接多个设备
[ ] 提供用于监控的 Web 界面
[ ] 缓存常用命令
[ ] 提供详细的操作日志
[ ] 支持自定义命令
[ ] 与 scrcpy 集成以实现可视化控制

🤝 贡献指南

Fork 此项目
创建分支：git checkout -b minha-feature
提交更改：git commit -m '新功能'
推送分支：git push origin minha-feature
提交 Pull Request

📄 许可证

本项目采用 MIT 许可证，可自由使用！

📞 支持

常见问题

💡 使用建议

确认 uv 是否已安装：uv --version

确认代码中 ADB 的路径

在使用 MCP 之前手动测试 ADB

检查 Claude Desktop 的日志以查找错误

确保设备已授权 USB 调试

高级调试

# 手动测试 ADB
"C:\Users\Cristiano\Programação\ADB\adb.exe" devices

# 测试特定命令
"C:\Users\Cristiano\Programação\ADB\adb.exe" shell "getprop ro.build.version.release"

# 检查 Python 是否能找到 MCP
uv run python -c "import mcp; print('MCP OK')"

mcp_adb