Mcp Android Agent Python

MCP Android Agent

本项目提供了一个 MCP（Model Context Protocol） 服务，用于通过 uiautomator2 自动化 Android 设备。它旨在轻松接入 GitHub Copilot Chat、Claude 或 Open Interpreter 等 AI Agent，从而通过自然语言控制 Android 设备。

模块化架构

该服务已重构为清晰、模块化的架构，工具按功能进行组织：

mcp-android-server-python/
├── server.py                    # Main server (61 lines - clean & focused)
├── server_original_backup.py    # Backup of original monolithic version
└── tools/                       # 🆕 Modular tools package
    ├── __init__.py             # Central registration & imports
    ├── device_tools.py         # Device connection & status tools
    ├── app_tools.py            # Application management tools
    ├── screen_tools.py         # Screen control & unlock tools
    ├── input_tools.py          # User input simulation (click, swipe, text)
    ├── inspection_tools.py     # UI inspection & screenshots
    └── advanced_tools.py       # Advanced features (toast, activity wait)

模块化架构的优势

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

快速演示

---

环境要求

• Python 3.13 或更高版本
• 已安装 Android Debug Bridge（adb）并加入 PATH
• 已连接启用 USB 调试的 Android 设备
• 与 uiautomator2 兼容的 Android 设备

功能特性

设备管理

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

应用管理

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

屏幕与显示控制

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

用户输入模拟

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

UI 检查与调试

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

高级能力

• Toast 检测：捕获系统 Toast 消息以进行验证
• Activity 监控：等待特定的 Android Activity
• 后台操作：为耗时操作提供异步支持

使用场景

非常适合：

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

安装

1. 克隆仓库

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

2. 创建并激活虚拟环境

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

3. 安装依赖

uv pip install

运行服务

该服务支持两种不同的传输模式，具体取决于你的使用场景：

方式 1：MCP stdio（用于 AI Agent 集成）

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

# Edit server.py to use stdio mode (default commented out)
# Uncomment the stdio section and comment out http section

# Then run:
uv run python server.py

方式 2：Streamable HTTP（用于 Web/API 集成）

此模式将服务作为 HTTP API 运行，适用于 Web 应用、curl 测试或直接 HTTP 调用。

# Current default configuration - runs as HTTP server
uv run python server.py

# Server will be available at: http://localhost:8080

在模式之间切换

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

用于 stdio 模式（AI Agent）：

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 Agent 集成（Claude Desktop、VS Code 等）

使用此服务需要一个 MCP 客户端。Claude Desktop 应用就是一个 MCP 客户端的示例。

重要： 用于 AI Agent 集成时，请确保以 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 配合使用

你也可以将此 MCP 服务与 VS Code 的 Agent 模式配合使用（需要 VS Code 1.99 或更高版本）。设置方法：

1. 在你的工作区中创建一个 .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: List Servers 查看和管理已配置的服务
• 命令面板 → MCP: Start Server 启动服务
• 该服务的工具将在 VS Code 的 Agent 模式聊天中可用

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

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

# Check if server is running
curl http://localhost:8080/

# List available tools (you'll need to implement proper tool discovery endpoints)
# This depends on your FastMCP version and configuration

HTTP 模式的适用场景：

• 带 Android 自动化的 Web 应用
• 无法使用 stdio 的测试工具
• 与其他服务的直接 API 集成
• 使用 curl/Postman 进行调试和开发

UI Inspector

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

1. 安装 UI inspector：

uv pip install uiautodev

2. 启动 inspector：

uiauto.dev

3. 打开浏览器并访问 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	获取屏幕上显示的最后一条 toast 消息
wait_activity	等待直到出现特定的 activity

---

许可证

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