# MCP安卓控制服务器
## 基本信息
- Slug: `nim444-mcp-android-server-python`
- Source: modelscope
- Publisher: @nim444/mcp-android-server-python
- Categories: autonomous-agents / app-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@nim444/mcp-android-server-python
## 简介
一种模型上下文协议服务器，它通过自然语言使人工智能代理能够控制和自动化安卓设备，支持应用程序管理、用户界面交互和设备监控等操作。
## MCP Server 详情

[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/) [![CI Pipeline](https://github.com/nim444/mcp-android-server-python/actions/workflows/ci.yml/badge.svg?branch=main&label=CI%20Pipeline)](https://github.com/nim444/mcp-android-server-python/actions/workflows/ci.yml) [![Coverage: 90%](https://img.shields.io/badge/Coverage-90%25-brightgreen.svg)](https://codecov.io/gh/nim444/sdet-django-api) [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# MCP Android Agent

该项目提供了一个**MCP（Model Context Protocol）**服务器，用于通过[uiautomator2](https://github.com/openatx/uiautomator2)自动化Android设备。它设计为可以轻松地与像GitHub Copilot Chat、Claude或Open Interpreter这样的AI代理集成，通过自然语言控制Android设备。

## 快速演示

![演示](.docs/demo.gif)

## 要求

- Python 3.13 或更高版本
- 已安装并添加到PATH中的Android Debug Bridge (adb)
- 连接的启用了USB调试的Android设备
- [uiautomator2](https://github.com/openatx/uiautomator2)兼容的Android设备

## 功能

- 通过包名启动、停止和管理应用程序
- 检索已安装的应用程序和当前前台应用
- 点击、滑动、滚动、拖动以及执行UI交互
- 获取设备信息、屏幕分辨率、电池状态等
- 捕获屏幕截图或最后的Toast消息
- 以编程方式解锁、唤醒或使屏幕休眠
- 清除应用程序数据并等待活动
- 包含健康检查和`adb`诊断工具

## 使用场景

非常适合：

- 需要与真实设备交互的AI代理
- 远程设备控制设置
- 自动化QA工具
- Android机器人框架
- UI测试和自动化
- 设备管理和监控

## 安装

### 1. 克隆仓库

bash
git clone https://github.com/nim444/mcp-android.git
cd mcp-android


### 2. 创建并激活虚拟环境

bash
# 使用uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate


### 3. 安装依赖项

bash
uv pip install


## 运行服务器

### 选项1：使用uvicorn（推荐）

bash
uvicorn server:app --factory --host 0.0.0.0 --port 8000


### 选项2：使用MCP stdio（用于AI代理集成）

bash
python server.py


## 使用方法

需要一个MCP客户端来使用此服务器。Claude Desktop应用程序就是一个MCP客户端的例子。要将此服务器与Claude Desktop一起使用：

### 找到你的Claude Desktop配置文件

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

### 将Android MCP服务器配置添加到mcpServers部分

json
{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}


将`/path/to/mcp-adb`替换为你克隆此仓库的绝对路径。例如：`/Users/username/Projects/mcp-adb`

### 与VS Code一起使用

您还可以将此MCP服务器与VS Code的代理模式一起使用（需要VS Code 1.99或更新版本）。要设置：

1. 在您的工作区中创建一个`.vscode/mcp.json`文件：

json
{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}


将`/path/to/mcp-adb`替换为你克隆此仓库的绝对路径。

添加配置后，您可以使用以下命令管理服务器：
- 命令面板 → `MCP: List Servers` 查看和管理已配置的服务器- 命令面板 → `MCP: Start Server` 以启动服务器
- 服务器的工具将在 VS Code 的代理模式聊天中可用

![Vscode](.docs/mcp-vscode.png)

## UI 检查器

项目包括对 uiauto.dev 的支持，这是一个强大的 UI 检查工具，用于查看和分析设备的界面结构。

1. 安装 UI 检查器：

bash
pip install uiautodev


2. 启动检查器：

bash
uiauto.dev


3. 打开浏览器并导航到 <https://uiauto.dev>

![Ui](.docs/ui.png)

## 可用的 MCP 工具

| 工具名称             | 描述                                                              |
|-----------------------|--------------------------------------------------------------------------|
| `mcp_health`          | 检查 MCP 服务器是否正常运行                              |
| `connect_device`      | 连接到 Android 设备并获取基本信息                          |
| `get_installed_apps`  | 列出所有已安装的应用程序及其版本和包信息                    |
| `get_current_app`     | 获取当前在前台的应用程序的信息                       |
| `start_app`           | 通过包名启动应用程序                                         |
| `stop_app`            | 通过包名停止应用程序                                          |
| `stop_all_apps`       | 停止所有当前正在运行的应用程序                                          |
| `screen_on`           | 打开屏幕                                                       |
| `screen_off`          | 关闭屏幕                                                      |
| `get_device_info`     | 获取详细的设备信息：序列号、分辨率、电池等              |
| `press_key`           | 模拟硬件按键按下（例如 `home`、`back`、`menu` 等）          |
| `unlock_screen`       | 解锁屏幕（如果需要则打开并滑动）                       |
| `check_adb`           | 检查 ADB 是否已安装并列出连接的设备                     |
| `wait_for_screen_on`  | 异步等待直到屏幕打开                        |
| `click`               | 通过 `text`、`resourceId` 或 `description` 点击元素              |
| `long_click`          | 对元素执行长按                                       |
| `send_text`           | 在当前焦点字段中输入文本（可选地先清除）     |
| `get_element_info`    | 获取 UI 元素的信息（文本、边界、可点击等）                  |
| `swipe`               | 从一个坐标滑动到另一个坐标                                     |
| `wait_for_element`    | 等待元素出现在屏幕上                                  |
| `screenshot`          | 从设备上截取并保存屏幕截图                               |
| `scroll_to`           | 滚动直到给定元素可见                             |
| `drag`                | 将元素拖动到特定的屏幕位置                            |
| `get_toast`           | 获取屏幕上显示的最后一个 toast 消息                               |
| `clear_app_data`      | 清除指定应用的用户数据/缓存                                 |
| `wait_activity`       | 等待特定活动出现                                   |

---

## 许可证

本项目根据 MIT 许可证许可 - 详情请参阅 [LICENSE](LICENSE) 文件。