项目简介

本项目是一个基于Model Context Protocol (MCP) 的Python服务器实现，旨在提供通过AI代理（如GitHub Copilot Chat, Claude, Open Interpreter等）控制和自动化Android设备的能力。它利用 'uiautomator2' 库与Android设备进行交互，将常见的Android操作封装为MCP工具，供客户端调用。

主要功能点

应用管理: 启动、停止、获取已安装应用列表、获取当前前台应用。
UI交互: 点击、长按、输入文本、滑动、滚动到指定元素。
设备状态: 获取设备信息（分辨率、电池、IP等）、开关屏幕、解锁屏幕、按键模拟。
屏幕操作: 截取屏幕截图。
自动化辅助: 等待元素出现、等待Activity出现、获取Toast消息、清除应用数据。
ADB诊断: 检查ADB工具状态并列出已连接设备。

安装步骤

克隆仓库: 将项目的代码库克隆到本地计算机。

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

创建并激活虚拟环境: 为了隔离项目依赖，建议使用虚拟环境。

# 使用 uv (或其他工具如 venv/conda)
uv venv
source .venv/bin/activate # Windows 用户请使用 .venv\\Scripts\\activate

安装依赖: 进入项目目录，安装所需的Python库。
```
uv pip install
```
准备Android设备: 确保你的Android设备已连接到计算机，并已开启USB调试。ADB工具需要安装并添加到系统PATH环境变量中。

服务器配置 (供MCP客户端参考)

MCP服务器通过特定传输协议（如Stdio）与MCP客户端通信。客户端需要知道如何启动该服务器。典型的MCP客户端（如Claude Desktop, VS Code Agent）通过配置文件来管理MCP服务器连接。

以下是配置一个Stdio类型MCP服务器的示例结构说明：

{
  "mcpServers": {
    "your-server-name": { // 自定义一个唯一的服务器名称
      "type": "stdio",    // 传输协议类型，本项目支持 stdio
      "command": "...",   // 启动Python解释器或shell的命令
      "args": [...]       // 传递给命令的参数列表
    }
  }
}

对于本项目，'command' 和 'args' 需要指向你的Python环境和 'server.py' 文件。根据安装步骤，服务器通常在激活虚拟环境后通过运行 'python server.py' 启动。如果需要先切换到项目目录并激活虚拟环境，可以使用shell命令作为启动命令。

例如，在macOS或Linux上（假设项目路径为 '/path/to/mcp-android'）：

'command': '"bash"'
'args': '["-c", "cd /path/to/mcp-android && source .venv/bin/activate && python server.py"]'

请将 '/path/to/mcp-android' 替换为你实际的项目路径。Windows用户请使用相应的命令来激活虚拟环境并运行Python脚本。

基本使用方法

启动MCP服务器: 根据 README 提供的两种方式之一启动服务器。对于与AI代理集成，通常使用Stdio方式：

# 确保你已经在项目目录下并激活了虚拟环境
python server.py

或者按照客户端配置中的 'command' 和 'args' 直接由客户端启动。

配置MCP客户端: 按照你的MCP客户端（如Claude Desktop, VS Code）的文档，编辑其配置文件，添加上述“服务器配置”中说明的条目，指向你本地的 'mcp-android-server-python' 项目。
通过客户端调用工具: 启动MCP客户端。如果配置正确，客户端应该能检测到并连接到该MCP服务器，并识别服务器暴露的工具能力。你现在可以通过客户端的界面或交互方式（如在聊天中提及工具）来调用该服务器提供的Android自动化工具，实现对连接设备的控制。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供MCP客户端参考)

基本使用方法

信息