Metadata-Version: 2.4
Name: android-adb
Version: 0.1.0
Summary: 用于 Android 自动化的 MCP 服务器
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/xuegao-tzx/android-adb-mcp
Project-URL: Repository, https://github.com/xuegao-tzx/android-adb-mcp
Keywords: android,adb,mcp,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.26.0
Requires-Dist: pure-python-adb>=0.3.0.dev0
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: Pillow>=12.1.1
Requires-Dist: pytesseract>=0.3.13
Dynamic: license-file

# Android MCP 服务器

一个通过 ADB（Android Debug Bridge）提供 Android 设备编程控制的 MCP（Model Context Protocol）服务器。该服务器暴露多种 Android 设备管理能力，可被 MCP 客户端访问，例如 [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) 和代码编辑器（如 [Cursor](https://docs.cursor.com/context/model-context-protocol)、[Kiro](https://kiro.dev)）。

## 功能特性

- 🔧 ADB 命令执行
- 📸 设备屏幕截图
- 🔍 截图 OCR 文字识别
- 🎯 UI 布局分析
- 📱 设备应用包管理
- 👆 触摸操作（点击、滑动、长按、文本输入、按键）
- 🚀 应用管理（启动、停止、安装、卸载）
- 📂 文件传输（推送、拉取）
- 🔋 设备信息与电池状态
- 📹 屏幕录制
- 📋 日志获取
- 📶 WiFi 开关控制
- ⏳ 元素等待

## 前置要求

- Python 3.11+
- ADB（Android Debug Bridge）已安装并配置
- Android 设备或模拟器（模拟器未经测试）
- Tesseract OCR 引擎（用于文字识别功能）

## 安装

### 方式一：通过 pip 安装（推荐）

```bash
pip install android-adb
```

### 方式二：通过 uvx 直接运行（无需安装）

```bash
uvx android-adb
```

### 方式三：从源码安装

```bash
git clone https://github.com/xuegao-tzx/android-adb-mcp.git
cd android-adb-mcp
uv pip install -e "."
```

### 安装 Tesseract OCR 引擎

```bash
# Ubuntu/Debian
sudo apt install tesseract-ocr

# macOS (使用 Homebrew)
brew install tesseract

# Windows
# 从以下地址下载安装程序: https://github.com/UB-Mannheim/tesseract/wiki
```

## 配置

服务器支持灵活的设备配置，适用于多种使用场景。

### 配置文件查找顺序

服务器会按以下顺序查找 `config.yaml`：

1. 当前工作目录下的 `config.yaml`
2. `~/.android-adb/config.yaml`（用户 home 目录）

如果未找到配置文件，服务器会在仅连接一个设备时自动选择。

### 设备选择模式

**1. 自动选择（单设备推荐）**

- 无需配置文件
- 自动连接唯一已连接的设备

**2. 手动指定设备**

创建 `config.yaml`：

```yaml
device:
  name: "your-device-serial-here"  # 来自 'adb devices' 的设备标识符
```

### 查找设备序列号

```bash
adb devices
```

输出示例：

```
List of devices attached
13b22d7f        device
emulator-5554   device
```

使用第一列的值作为设备名称。

### 使用场景

| 场景 | 是否需要配置 | 行为 |
|------|-------------|------|
| 单设备连接 | 不需要 | ✅ 自动连接该设备 |
| 多设备，指定某一个 | 需要 `config.yaml` | ✅ 连接到指定设备 |
| 多设备，无配置 | 不需要 | ❌ 显示错误并列出可用设备 |
| 无设备连接 | 不适用 | ❌ 显示"无设备"错误 |

## 使用方法

需要 MCP 客户端来使用此服务器。

### Claude Desktop

在 Claude Desktop 配置文件中添加：

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

**pip 安装方式：**

```json
{
  "mcpServers": {
    "android": {
      "command": "android-adb"
    }
  }
}
```

**uvx 方式（无需预安装）：**

```json
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": ["android-adb"]
    }
  }
}
```

### Kiro / Cursor 等编辑器

在项目的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": ["android-adb"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 可用工具

服务器暴露以下 41 个工具：

#### 基础工具

| 工具 | 说明 |
|------|------|
| `list_devices()` | 列出所有已连接的 Android 设备及其状态 |
| `get_packages()` | 获取设备上所有已安装的应用包名 |
| `execute_adb_shell_command(command)` | 执行 ADB shell 命令并返回输出 |
| `get_uilayout()` | 获取当前界面中可点击元素的信息 |
| `get_screenshot()` | 截取设备屏幕截图并返回 |
| `get_screenshot_ocr(search_string, confidence_threshold)` | 在截图中搜索指定文本并返回位置坐标 |
| `get_screenshot_text(confidence_threshold)` | 使用 OCR 获取截图中的所有文本及坐标 |
| `get_package_action_intents(package_name)` | 获取指定包的所有非数据 Action |

#### 触摸与输入操作

| 工具 | 说明 |
|------|------|
| `tap(x, y)` | 点击屏幕指定坐标 |
| `double_tap(x, y, interval)` | 双击屏幕指定坐标 |
| `long_press(x, y, duration)` | 长按屏幕指定坐标 |
| `swipe(x1, y1, x2, y2, duration)` | 从一个坐标滑动到另一个坐标 |
| `pinch_zoom(cx, cy, scale, duration)` | 在指定中心点执行缩放手势 |
| `input_text(text)` | 在当前焦点输入框中输入文本 |
| `press_key(keycode)` | 发送按键事件（HOME/BACK/ENTER 等） |

#### 应用管理

| 工具 | 说明 |
|------|------|
| `launch_app(package_name)` | 启动指定应用 |
| `start_activity(package_name, activity_name, extras)` | 启动指定 Activity |
| `stop_app(package_name)` | 强制停止指定应用 |
| `clear_app_data(package_name)` | 清除指定应用的所有数据 |
| `install_apk(apk_path)` | 安装 APK 到设备 |
| `uninstall_app(package_name)` | 卸载指定应用 |
| `get_current_activity()` | 获取当前前台 Activity 的包名和类名 |
| `open_url(url)` | 在设备上打开指定 URL |
| `grant_permission(package_name, permission)` | 授予应用运行时权限 |
| `revoke_permission(package_name, permission)` | 撤销应用运行时权限 |

#### 设备信息与文件管理

| 工具 | 说明 |
|------|------|
| `get_device_info()` | 获取设备基础信息（型号、系统版本、分辨率等） |
| `get_battery_info()` | 获取电池信息（电量、充电状态、温度等） |
| `push_file(local_path, remote_path)` | 推送本地文件到设备 |
| `pull_file(remote_path, local_path)` | 从设备拉取文件到本地 |
| `list_files(remote_path)` | 列出设备上指定目录的文件和文件夹 |

#### 设备设置

| 工具 | 说明 |
|------|------|
| `set_wifi(enable)` | 开启或关闭 WiFi |
| `set_bluetooth(enable)` | 开启或关闭蓝牙 |
| `toggle_airplane_mode()` | 切换飞行模式 |
| `set_screen_brightness(level)` | 设置屏幕亮度（0-255） |
| `set_screen_orientation(orientation)` | 设置屏幕方向（auto/portrait/landscape 等） |

#### 剪贴板

| 工具 | 说明 |
|------|------|
| `get_clipboard()` | 获取设备剪贴板内容 |
| `set_clipboard(text)` | 设置设备剪贴板内容 |

#### 进阶能力

| 工具 | 说明 |
|------|------|
| `record_screen(duration)` | 录制设备屏幕，最大 180 秒 |
| `get_logcat(filter_expr, lines)` | 获取设备日志 |
| `clear_logcat()` | 清除日志缓冲区 |
| `wait_for_element(text, timeout)` | 等待指定文本的元素出现在界面上 |

## 贡献

欢迎贡献代码！

## 致谢

- 基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 构建
