终极安卓MCP服务器

Name: 终极安卓MCP服务器
Author: oddlyspaced

作者：oddlyspaced11 星标更新：2025-04-27

安装使用来源：spider==github.com

项目介绍

Ultimate Android MCP 🤖

📝 描述

Ultimate Android MCP 是一个强大的多功能 MCP（模型上下文协议）服务器，旨在与连接的 Android 设备进行交互。它提供了一系列工具和功能，可以在 Android 设备上执行各种任务，如管理应用程序、与用户界面交互、检索设备信息等。该项目旨在通过使用模型上下文协议的大型语言模型实现最佳交互。

✨ 功能

MCP 服务器提供了以下功能：

📱 应用程序管理

检索所有已安装的包列表（系统和用户安装的）。
检索用户安装的应用程序包名称列表。
检索系统应用程序包名称列表（预装应用）。
通过包名称启动应用程序。
在连接的 Android 设备上安装 APK。
从设备中卸载指定的包。
检查指定的包是否已安装在设备上。

🎮 输入模拟

模拟输入事件，如按键、点击、滑动和文本输入。
模拟具有指定键码的按键事件。
在指定的 (x, y) 坐标处模拟点击手势。
在当前聚焦的字段中模拟输入文本。
模拟具有指定键码的按键事件。
模拟具有指定 dx 和 dy 值的滚动手势。
从一个坐标到另一个坐标模拟滑动手势，可选持续时间。
检查虚拟键盘是否当前打开。
模拟返回按钮的点击。
模拟主页按钮的点击。

📊 设备信息

检索设备特定信息，包括序列号、属性和电池电量。
检索连接的 Android 设备的序列号。
检索设备的 build.prop 属性。
检索设备覆盖配置属性。
检索设备的电池电量。
检索设备的屏幕密度。
检索设备的屏幕尺寸。

🖥️ 系统和性能监控

检索 CPU 信息，如核心数和负载百分比。
检索设备上的 CPU 核心数。
检索设备上的当前 CPU 负载百分比。
检索顶级活动和进程。
检索指定包名称的进程 ID (PID)。
检索设备当前顶部的活动。
检索设备当前顶部的单一活动。

📂 文件管理

管理设备上的文件，包括推送和拉取文件。
从连接的 Android 设备拉取文件到本地机器。
将文件从本地机器推送到连接的 Android 设备。

🖱️ 用户界面交互

检索设备屏幕上显示的 UI 元素和聚焦节点。
检索当前在设备屏幕上可见的 UI 节点列表，重点关注文本标签和内容描述。
检索当前在设备屏幕上聚焦的 UI 节点列表。

⚙️ 高级操作

执行原始 ADB shell 命令并检索输出。

🎥 演示

USB 连接的物理设备（运行 Android 15 的 Pixel 7 Pro），其屏幕通过 scrcpy 分享。使用 Claude for Desktop（版本 0.9.2）。提供给 Claude 的文本如下：

在连接的 Android 设备上播放 Future 的歌曲《Mask Off》。

Claude 然后确定了如何启动应用程序，点击哪个按钮以及在哪里输入文本。演示中的所有操作都是自主完成的，无需用户干预。

https://github.com/user-attachments/assets/5811fcc1-9047-48be-b057-1049754710c0

📋 先决条件

要运行此项目，请确保您具备以下条件：

Python 3。
已安装并配置在系统上的 ADB（Android 调试桥）（确保 adb 命令可以工作）。
启用了 USB 调试的连接 Android 设备。
安装了 pure-python-adb 库（包含在项目依赖项中）。

⚙️ 安装和设置

按照以下步骤设置项目：

克隆存储库：

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

安装所需的库：

默认情况下，此项目使用 uv 进行依赖管理，但如果您喜欢，也可以通过 pip 安装所需的包。
```
uv sync
```
或
```
pip install pure-python-adb
pip install mcp
```
通过编辑 config.py 文件来配置项目，以匹配您的 ADB 设置和设备详情。（更多信息见下一节）

运行 doctor.py 以确保设置正确。

这是 doctor.py 脚本的参考响应：

使用以下配置检查设备连接：
ADB 客户端主机：127.0.0.1
ADB 客户端端口：5037
ADB 设备序列号：32241FDH3002EH

设备已连接：32241FDH3002EH
来自 Android 的问候！准备好与 MCP 一起使用。

🛠️ 配置概述

config.py 文件包含以下配置选项：

adb_client_host：ADB 服务器的主机地址（默认：127.0.0.1）。
adb_client_port：ADB 服务器的端口（默认：5037）。
adb_device_serial：连接设备的序列号或 IP 地址。如果没有指定，则使用第一个可用设备。

🖥️ 通过 Claude MCP 配置 JSON 使用

要使用 MCP 服务器，可以通过 Claude Desktop MCP 配置 JSON 与其交互。

Claude Desktop 配置文件位于以下位置：

Windows：%APPDATA%\Claude\claude_desktop_config.json

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

这是一个使用 uv 的示例配置：

{
  "mcpServers": {
    "Android MCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/hardik/Projects/Android-Agents/android-mcp", // 替换为您自己的文件夹路径
        "run",
        "server.py"
      ]
    }
  }
}

或者使用 python

{
  "mcpServers": {
    "Android MCP": {
      "command": "python",
      "args": [
        "/Users/hardik/Projects/Android-Agents/android-mcp/server.py", // 替换为您自己的文件夹路径
      ]
    }
  }
}

或者，您可以使用以下命令运行 MCP 服务器：

python server.py

🐞 已知问题

经常连续查询用户界面时，结果可能会暂时不可用，除非重启设备。这是由于当前 UI 树的转储问题。逻辑将更新以尽快解决此问题。

💻 使用的技术

贡献者

Hardik Srivastava (oddlyspaced)

📜 许可证

本项目根据 GNU 通用公共许可证 v3.0 授权。您可以在以下网址获取许可证副本：

https://www.gnu.org/licenses/gpl-3.0.en.html

该许可证允许您使用、修改和分发软件，前提是任何修改或衍生作品也必须授权于 GPL。更多详情，请参阅许可文档。