内容
# Android MCP 服务器
[](https://github.com/username/android-mcp-server/actions)
[](https://codecov.io/gh/username/android-mcp-server)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
一个强大的MCP（模型上下文协议）服务器，提供全面的Android设备自动化功能，通过ADB（Android Debug Bridge）。该服务器使AI代理和自动化工具能够与Android设备交互，以进行测试、自动化和设备控制任务。
https://github.com/user-attachments/assets/68f3df22-fcf1-49af-8715-fcfa05496c90
## 🚀 功能
### 设备管理
- **多设备支持**：同时连接和管理多个Android设备
- **自动发现**：自动检测和选择设备
- **健康监测**：实时设备状态和连接检查
- **设备信息**：完整的设备规格和功能
### UI自动化
- **布局检查**：提取完整的UI层次结构，包含元素详细信息
- **智能元素查找**：通过文本、资源ID、内容描述或类查找UI元素
- **手势控制**：点击、滑动和多点触控手势支持
- **文本输入**：发送文本和按键事件（返回、主页、菜单等）
### 媒体捕获
- **截图**：高质量截图，支持自定义选项
- **屏幕录制**：MP4视频录制，支持质量控制
- **批量操作**：多个并发录制会话
### 高级监控
- **实时日志监控**：实时logcat流式传输，支持过滤
- **多会话支持**：并发日志监控，支持不同过滤器
- **导出功能**：保存日志和媒体到本地文件系统
## 📋 前置条件
### 必需软件
- **Python 3.11+**：运行时环境
- **Android SDK 平台工具**：用于ADB功能
- **启用USB调试**：在目标Android设备上
### ADB设置
1. **安装Android SDK 平台工具**：
```bash
# macOS (via Homebrew)
brew install android-platform-tools
# Ubuntu/Debian
sudo apt install android-tools-adb
# Windows
# 从 https://developer.android.com/tools/releases/platform-tools 下载
```
2. **验证ADB安装**：
```bash
adb version
# 输出：Android Debug Bridge 版本 x.x.x
```
3. **在Android设备上启用USB调试**：
- 进入 设置 → 关于手机
- 点击“版本号”7次以启用开发者选项
- 进入 设置 → 开发者选项
- 启用“USB调试”
- 通过USB连接设备并在提示时授权
## ⚙️ 安装
### 使用uv（推荐）
```bash
git clone <仓库地址>
cd android-mcp-server
uv sync
```
### 使用pip
```bash
git clone <仓库地址>
cd android-mcp-server
pip install -e .
```
### 验证安装
```bash
# 检查设备是否被检测到
adb devices
# 测试服务器启动
python -m src.server
```
## 🚀 快速开始
### 基本用法示例
```python
import asyncio
from mcp import ClientSession
async def demo_automation():
# 连接到MCP服务器
session = ClientSession()
# 获取连接的设备
devices = await session.call_tool("get_devices")
print(f"找到 {devices['count']} 个设备")
# 截取屏幕截图
screenshot = await session.call_tool("take_screenshot", {
"filename": "demo_screenshot.png"
})
# 查找并点击按钮
elements = await session.call_tool("find_elements", {
"text": "设置",
"clickable_only": True
})
if elements["count"] > 0:
result = await session.call_tool("tap_element", {
"text": "设置"
})
print("点击了设置按钮")
# 运行演示
asyncio.run(demo_automation())
```
### 命令行用法
```bash
# 启动MCP服务器
python -m src.server
# 或使用已安装的脚本
android-mcp-server
```
## 🛠️ 可用工具
### 设备管理
- **`get_devices()`**：列出所有连接的Android设备
- **`select_device(device_id?)`**：选择特定的设备或自动选择第一个可用设备
- **`get_device_info()`**：获取详细的设备信息和屏幕规格
### UI交互
- **`get_ui_layout(compressed?, include_invisible?)`**：提取完整的UI层次结构
- **`find_elements(...)`**：通过文本、资源ID、内容描述或类查找UI元素
- **`tap_screen(x, y)`**：在特定屏幕坐标处点击
- **`tap_element(text?, resource_id?, content_desc?, index?)`**：查找并点击UI元素
- **`swipe_screen(start_x, start_y, end_x, end_y, duration_ms?)`**：在坐标之间滑动
- **`swipe_direction(direction, distance?, duration_ms?)`**：在指定方向滑动
- **`input_text(text, clear_existing?)`**：输入文本到焦点字段
- **`press_key(keycode)`**：按下设备按键（返回、主页、回车等）
### 媒体捕获
- **`take_screenshot(filename?, pull_to_local?)`**：捕获设备截图
- **`start_screen_recording(...)`**：开始屏幕录制，支持质量选项
- **`stop_screen_recording(recording_id?, pull_to_local?)`**：停止录制会话
- **`list_active_recordings()`**：列出所有活跃的录制会话
### 日志监控
- **`get_logcat(tag_filter?, priority?, max_lines?, clear_first?)`**：获取设备日志
- **`start_log_monitoring(tag_filter?, priority?, output_file?)`**：开始连续日志监控
- **`stop_log_monitoring(monitor_id?)`**：停止日志监控会话
- **`list_active_monitors()`**：列出活跃的监控会话
## 🔌 MCP服务器安装
### 添加到Claude Desktop（推荐）
1. **定位Claude Desktop配置文件**：
```bash
# macOS
~/Library/Application Support/Claude/claude_desktop_config.json
# Windows
%APPDATA%/Claude/claude_desktop_config.json
```
2. **添加Android MCP服务器**：
```json
{
"mcpServers": {
"android-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/android-mcp-server",
"run",
"android-mcp-server"
]
}
}
}
```
3. **重启Claude Desktop** 以激活服务器。
### 替代安装方法
#### 直接使用Python
```json
{
"mcpServers": {
"android-mcp-server": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/android-mcp-server"
}
}
}
```
#### 使用pip安装包
```bash
pip install -e /path/to/android-mcp-server
```
```json
{
"mcpServers": {
"android-mcp-server": {
"command": "android-mcp-server"
}
}
}
```
## 🤖 AI代理用法示例
### 基本设备交互
```
"截取当前Android设备屏幕截图，然后查找所有包含'Settings'的按钮"
"连接到Android设备，点击设置应用，然后截取另一个截图"
"从屏幕顶部向下滑动以打开通知面板，然后捕获显示的内容"
```
### 应用测试和自动化
```
"启动计算器应用，执行计算25 + 37，并验证结果是62"
"测试登录流程：查找用户名字段，输入'testuser'，查找密码字段，输入'password123'，然后点击登录按钮"
"遍历应用的主菜单，点击每个菜单项并截取每个页面的截图"
```
### UI分析和调试
```
"提取当前屏幕的完整UI布局并标识所有可点击元素"
"查找此屏幕上的所有文本输入字段并告诉我哪些字段当前有焦点"
"检查是否有任何可访问性问题，检查按钮是否有适当的描述"
```
### 日志监控和调试
```
"开始监控'MyApp'包的日志并显示我在接下来的2分钟内出现的任何错误"
"获取系统日志的最后50行，优先级级别为警告或更高"
"在执行下一个操作时监控网络相关的日志，然后显示我记录的内容"
```
### 性能测试
```
"记录应用启动序列的30秒视频，然后分析UI响应速度"
"在执行每个主要用户操作前后截取快照以记录用户流程"
"在遍历应用的不同屏幕时监控内存使用日志"
```
### 多设备测试
```
"列出所有连接的Android设备并选择分辨率最大的设备"
"切换到设备ID 'emulator-5554'并重复之前的测试序列"
"通过在每个设备上截取快照来比较不同设备上的相同UI元素"
```
## 💡 AI代理提示
### 高效的元素查找
- 始终使用`find_elements`然后再使用`tap_element`以验证元素是否存在
- 使用`exact_match: false`进行部分文本匹配，当元素文本可能发生变化时
- 结合多个搜索条件（文本+可点击_only）以实现更精确的定位
### 上下文日志监控
- 将`max_lines`限制在20-200以避免使AI上下文窗口过载
- 使用特定的`tag_filter`关注相关应用组件
- 根据需要的信息类型设置适当的`priority`级别（I/W/E）
### 截图驱动的工作流程
- 在操作前后截取截图进行验证
- 使用描述性文件名指示测试步骤或应用状态
- 自动将截图保存到`./assets/`以便于访问
### 强大的自动化模式
- 在开始自动化之前使用`get_device_info`检查设备连接
- 当元素查找失败时，使用`get_ui_layout`以了解当前屏幕结构
- 为间歇性UI状态问题实现重试逻辑
## 🏗️ 架构
服务器采用模块化架构：
- **`ADBManager`**：核心ADB通信和设备管理
- **`UILayoutExtractor`**：UI层次结构解析和元素提取
- **`ScreenInteractor`**：触摸和手势处理
- **`MediaCapture`**：截图和录制功能
- **`LogMonitor`**：实时日志监控和过滤
- **`FastMCP`**：MCP协议实现和工具注册
## 🤝 贡献
欢迎贡献！请随意提交问题和拉取请求。
### 开发设置
```bash
git clone <仓库地址>
cd android-mcp-server
uv sync --dev
```
### 运行测试
```bash
# 安装测试依赖
pip install -e ".[test,dev]"
# 运行完整的测试套件并生成覆盖率报告
python -m pytest tests/ --cov=src --cov-fail-under=80
# 运行特定类别的测试
python -m pytest tests/ -m "unit" # 仅限单元测试
python -m pytest tests/ -m "integration" # 集成测试
python -m pytest tests/ -m "not slow" # 跳过慢速测试
# 运行代码质量检查
make code-quality # 或运行个别工具：
flake8 src
pydocstyle src --convention=google
```
## 📄 许可证
该项目根据MIT许可证授权 - 参见LICENSE文件了解详细信息。
## 🔗 相关项目
- [MCP规范](https://modelcontextprotocol.io/)
- [Android Debug Bridge（ADB）](https://developer.android.com/tools/adb)
- [uiautomator](https://developer.android.com/training/testing/other-components/ui-automator)
