内容
# ADB MCP
Model Context Protocol (MCP) 服务器，通过 ADB 控制 Android 设备，实现智能屏幕交互和自动化操作。
## 功能特性
- 📱 ADB 设备控制（截图、点击、滑动、输入等）
- 🎯 Set-of-Marks (SOM) 标注截图技术
- 🤖 智能坐标解析和点击（OCR + SOM）
- 🔧 MCP 协议兼容（stdio 模式）
## 环境要求
- macOS/Linux/Windows + ADB 已安装 + android Cli 已安装
- Android 设备通过 USB 连接并开启开发者模式
- [uv](https://docs.astral.sh/uv/) 包管理器
### Python 依赖项
- **mcp**: MCP SDK，提供 MCP 协议支持
- **easyocr**: OCR 文字识别（支持中英文）
- **torch**: PyTorch，EasyOCR 底层依赖
- **numpy**: 数值计算
- **fastapi / uvicorn / pydantic**: Web 框架（预留扩展）
## 安装
### 使用 uv 安装（推荐）
```bash
# 1. 克隆或下载项目
cd your/path/to/McpAdb
# 2. 安装依赖
uv sync
```
## 启动 MCP 服务
```bash
uv run mcp_server_fast.py
```
项目根目录已包含 `.mcp.json` 配置文件，使用 `uv run` 直接启动：
```json
{
"mcpServers": {
"adb-mcp": {
"command": "uv",
"args": ["run", "mcp_server_fast.py"],
"env": {},
"disabled": false
}
}
}
```
将 `.mcp.json` 放在项目根目录（或合并到 `~/.claude.json` 的 `mcpServers` 中），重启 Claude Code 即可自动加载 MCP 服务。
## MCP 工具列表
| 工具 | 说明 |
|------|------|
| `list_devices` | 列出所有已连接的安卓设备 |
| `take_screenshot` | 截图当前安卓屏幕。当用户要求点击、查找或操作屏幕时，必须先调用此工具获取最新画面 |
| `find_text_on_screen` | 使用 OCR 在屏幕截图中查找指定文本并返回坐标 |
| `tap_screen` | 在指定坐标点击屏幕 |
| `input_text_to_device` | 输入文本到当前焦点位置 |
| `swipe_screen` | 在屏幕上进行滑动操作 |
| `press_android_key` | 按下 Android 按键（如 KEYCODE_BACK, KEYCODE_HOME, KEYCODE_ENTER） |
| `go_to_home_screen` | 按 Home 键回到主屏幕 |
| `go_back_android` | 按返回键回到上一页 |
| `launch_android_app` | 启动 Android 应用 |
| `get_device_screen_size` | 获取设备屏幕尺寸 |
| `som_screenshot` | 拍摄带标注的截图（Set-of-Marks），标注屏幕上所有可交互元素的编号标签 |
| `get_tap_coordinates_by_id` | 解析 SOM 截图中数字标签对应的物理坐标 |
| `get_current_activity` | 获取当前活动/焦点应用 |
| `get_logcat_logs` | 获取 Logcat 日志（仅错误级别，支持 tail 参数） |
| `execute_shell_command` | 执行自定义 ADB shell 命令 |
| `install_android_app` | 安装 APK 文件 |
| `uninstall_android_app` | 卸载应用 |
| `push_file_to_device` | 推送文件到设备 |
| `pull_file_from_device` | 从设备拉取文件 |
| `wait_seconds` | 等待指定秒数 |
| `cleanup_screenshots` | 清理临时截图文件 |
## 项目结构
```
McpAdb/
├── adb_mcp/
│ ├── __init__.py # 包初始化
│ └── adb_controller.py # ADB 操作封装（截图、点击、输入等核心功能）
├── mcp_server_fast.py # MCP 服务器主入口（FastMCP stdio 模式）
├── pyproject.toml # 项目配置和依赖管理
├── .mcp.json # 项目级 MCP 配置
└── README.md # 项目文档
```
## 常见问题
### 设备未识别
```bash
# 检查设备连接
adb devices
# 重启 ADB 服务
adb kill-server && adb start-server
# 确保 USB 调试已启用
```
### 权限问题
```bash
# 给 ADB 可执行权限
chmod +x ~/Library/Android/sdk/platform-tools/adb
# 检查 ADB 路径
which adb
```
### 截图失败
- 确保设备已通过 USB 连接
- 确保开发者模式和 USB 调试已启用
- 尝试重新插拔 USB 线
- 检查 ADB 版本兼容性
## 许可证
本项目采用 MIT 许可证。
