MCP Android Agent

MCP安卓代理

该项目提供了一个 MCP（模型上下文协议） 用于自动化Android设备的服务器 自动化2。它被设计为可以轻松插入GitHub Copilot Chat、Claude或Open Interpreter等人工智能代理，通过自然语言控制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调试桥（adb）并位于PATH中
• 已连接启用USB调试的Android设备
• 自动化2 兼容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.创建并激活虚拟环境

# 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代理集成）

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

# 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：流式HTTP（用于Web/API集成）

此模式将服务器作为HTTP API运行，对于web应用程序、卷曲测试或直接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代理）：

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配置文件

• 窗户： %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代码一起使用

您还可以将此MCP服务器与VS Code的代理模式一起使用（需要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的代理模式聊天中可用

用于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检查器

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

1. 安装UI检查器：

uv pip install uiautodev

1. 启动检查器：

uiauto.dev

1. 打开浏览器并导航到

可用的MCP工具

设备管理工具

应用程序管理工具

屏幕控制工具

用户输入工具

检测工具

高级工具

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。