🚀 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')"