MCP安卓服务器Python

Name: MCP安卓服务器Python
Author: nim444

作者：nim44431 星标更新：2025-11-22

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

项目介绍

MCP Android Agent

该项目提供了一个用于通过uiautomator2自动化Android设备的**MCP（模型上下文协议）**服务器。它设计为可以轻松集成到GitHub Copilot Chat、Claude或Open Interpreter等AI代理中，通过自然语言控制Android设备。

模块化架构

服务器已经被重构为一个干净的模块化架构，工具按功能组织：

mcp-android-server-python/
├── server.py                    # 主服务器（61行 - 清晰且专注）
├── server_original_backup.py    # 原始单体版本的备份
└── tools/                       # 🆕 模块化工具包
    ├── __init__.py             # 中央注册及导入
    ├── device_tools.py         # 设备连接及状态工具
    ├── app_tools.py            # 应用管理工具
    ├── screen_tools.py         # 屏幕控制及解锁工具
    ├── input_tools.py          # 用户输入模拟（点击、滑动、文本）
    ├── inspection_tools.py     # UI检查及截图
    └── advanced_tools.py       # 高级功能（吐司消息、活动等待）

模块化架构的好处

可维护性：无需修改主服务器即可添加/修改/移除工具
组织性：工具按逻辑分组
测试性：每个工具模块可以单独进行单元测试
复用性：工具模块可以在其他项目中复用
扩展性：新的工具类别可以作为独立模块添加
干净代码：主服务器从1321行减少到61行

快速演示

要求

Python 3.13 或更高版本
安装并配置在PATH中的Android调试桥（adb）
连接并启用USB调试的Android设备
兼容uiautomator2的Android设备

功能

设备管理

智能设备检测：自动发现并连接可用设备
全面设备信息：获取序列号、分辨率、电池电量、WiFi IP地址、Android版本
ADB诊断：检查ADB可用性和连接状态
健康监控：内置服务器健康检查

应用管理

应用发现：列出所有已安装的应用（系统+用户应用）
应用生命周期控制：通过包名启动、停止、强制停止应用
应用状态监控：跟踪当前前台应用和活动
数据管理：清除应用数据/缓存以供测试

屏幕与显示控制

屏幕电源管理：编程方式开启/关闭屏幕
智能解锁：使用标准方法自动解锁屏幕
屏幕状态监控：等待屏幕激活（异步支持）

用户输入模拟

精准交互：通过文本、资源ID或内容描述点击
高级手势：长按、滑动、拖动操作
文本输入：智能文本输入，可选字段清空
硬件键：模拟主页、返回、菜单、音量键

UI检查与调试

元素分析：获取详细的UI元素属性和边界
屏幕捕获：拍摄屏幕截图用于调试和文档
UI层次结构：导出完整的屏幕结构为XML
智能等待：等待元素出现，自定义超时时间
滚动检测：自动滚动查找长列表中的元素

高级功能

吐司消息检测：捕获系统吐司消息以供验证
活动监控：等待特定的Android活动
后台操作：长时间操作的异步支持

使用场景

适用于：

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

安装

1. 克隆仓库

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

2. 创建并激活虚拟环境

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

3. 安装依赖

uv pip install

运行服务器

根据使用场景，服务器支持两种不同的传输模式：

选项1：MCP stdio（用于AI代理集成）

这是与Claude Desktop、VS Code或其他MCP客户端集成的标准模式。

# 编辑server.py以使用stdio模式（默认情况下被注释掉）
# 解注释stdio部分并注释http部分

# 然后运行：
uv run python server.py

选项2：流式HTTP（用于Web/API集成）

此模式下服务器作为HTTP API运行，适用于web应用程序、curl测试或直接HTTP调用。

# 当前默认配置 - 作为HTTP服务器运行
uv run python server.py

# 服务器将在以下地址可用：http://localhost:8080

切换模式

编辑server.py并修改if __name__ == "__main__":部分：

对于stdio模式（AI代理）：

if __name__ == "__main__":
    mcp.run(
        transport="stdio",
        show_banner=False,
    )

对于HTTP模式（Web API）：

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
    )

使用

与AI代理集成（Claude Desktop、VS Code等）

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

重要提示： 对于AI代理集成，请确保将服务器配置为stdio模式（参见“选项1”）。

要在Claude Desktop中使用此服务器：

查找你的Claude Desktop配置文件

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

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

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

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

与VS Code集成

你也可以使用VS Code的代理模式与此MCP服务器集成（需要VS Code 1.99或更新版本）。设置步骤如下：

在工作区创建一个.vscode/mcp.json文件：

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

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

添加配置后，你可以使用以下命令管理服务器：

命令面板 → MCP: 列出服务器 查看和管理已配置的服务器
命令面板 → MCP: 启动服务器 启动服务器
服务器的工具将在VS Code的代理模式聊天中可用

Vscode

与HTTP API集成（直接API调用）

当以HTTP模式运行（选项2）时，可以通过HTTP请求直接与服务器交互：

# 检查服务器是否正在运行
curl http://localhost:8080/

# 列出可用工具（你需要实现适当的工具发现端点）
# 这取决于你的FastMCP版本和配置

HTTP模式的使用场景：

具有Android自动化的web应用程序
不能使用stdio的测试工具
直接与其他服务的API集成
使用curl/Postman进行调试和开发

UI检查器

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

安装UI检查器：

uv pip install uiautodev

启动检查器：

uiauto.dev

打开浏览器并导航至 https://uiauto.dev

可用的MCP工具

设备管理工具

工具名称	描述
`mcp_health`	检查MCP服务器是否正常运行
`get_device_status`	获取完整的设备状态和准备情况信息
`connect_device`	连接到Android设备并获取基本信息
`get_device_info`	获取详细的设备信息：序列号、分辨率、电池电量等
`check_adb_and_list_devices`	检查ADB是否已安装并列出已连接的设备

应用管理工具

工具名称	描述
`get_installed_apps`	列出所有已安装的应用及其版本和包信息
`get_current_app`	获取当前前台应用的信息
`start_app`	通过包名启动应用
`stop_app`	通过包名停止应用
`stop_all_apps`	停止所有当前正在运行的应用
`clear_app_data`	清除指定应用的用户数据/缓存

屏幕控制工具

工具名称	描述
`screen_on`	开启屏幕
`screen_off`	关闭屏幕
`unlock_screen`	解锁屏幕（如果需要，打开并滑动）
`wait_for_screen_on`	异步等待屏幕开启

用户输入工具

工具名称	描述
`press_key`	模拟硬件按键按下（如`home`、`back`、`menu`等）
`click`	通过`text`、`resourceId`或`description`点击元素
`long_click`	对元素执行长按操作
`send_text`	输入文本到当前聚焦的字段（可选先清空）
`swipe`	从一个坐标滑动到另一个坐标
`drag`	将元素拖动到特定的屏幕位置

检查工具

工具名称	描述
`get_element_info`	获取UI元素的信息（文本、边界、可点击等）
`wait_for_element`	等待元素出现在屏幕上
`scroll_to`	滚动直到给定的元素变得可见
`screenshot`	从设备上拍摄并保存截图
`dump_hierarchy`	将当前屏幕的UI层次结构导出为XML

高级工具

工具名称	描述
`get_toast`	获取屏幕上最后显示的吐司消息
`wait_activity`	等待特定的活动出现

许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。