Android MCP Server：3步实现AI驱动的Android设备自动化控制

【免费下载链接】android-mcp-serverAn MCP server that provides control over Android devices via adb项目地址: https://gitcode.com/gh_mirrors/an/android-mcp-server

Android MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，通过 ADB (Android Debug Bridge) 为开发者和AI助手提供程序化的Android设备控制能力。该项目将Android设备管理功能封装为标准的MCP工具，使得Claude Desktop、Cursor等MCP客户端能够直接与Android设备交互，实现屏幕截图、UI布局分析、应用包管理等自动化操作。目标用户包括移动应用开发者、测试工程师、以及希望通过AI助手自动化Android设备操作的技术爱好者。

核心概念：理解Android MCP Server的架构原理

MCP协议基础与设备控制目标

Android MCP Server的核心设计理念是将复杂的Android设备操作抽象为简单的API调用，通过MCP协议暴露给AI助手。MCP (Model Context Protocol) 是Anthropic开发的开放协议，用于标准化AI助手与外部工具之间的交互。本项目实现了这一协议，将ADB命令封装为AI友好的工具接口。

项目架构基于三层设计：

1. MCP协议层：处理与客户端的标准通信协议
2. 业务逻辑层：封装Android设备的核心操作功能
3. ADB连接层：通过pure-python-adb库与设备建立连接

设备连接管理策略

设备连接是本项目的关键特性，支持多种配置模式：

设备连接的核心逻辑位于adbdevicemanager.py的AdbDeviceManager类中。当初始化时，系统会：

1. 检查ADB环境是否就绪
2. 获取当前连接的设备列表
3. 根据配置策略选择目标设备
4. 建立稳定的ADB连接

# 设备管理器的初始化流程 def __init__(self, device_name: str | None = None, exit_on_error: bool = True): # 1. 检查ADB安装状态 if not self.check_adb_installed(): raise RuntimeError("ADB not installed") # 2. 获取可用设备列表 available_devices = self.get_available_devices() # 3. 设备选择逻辑 if device_name: # 手动指定设备 if device_name not in available_devices: raise RuntimeError(f"Device {device_name} not found") selected_device_name = device_name else: # 自动选择逻辑 if len(available_devices) == 1: selected_device_name = available_devices[0] elif len(available_devices) > 1: raise RuntimeError("Multiple devices connected") # 4. 建立设备连接 self.device = AdbClient().device(selected_device_name)

实践步骤：5分钟快速部署与配置

环境准备与依赖安装

开始使用Android MCP Server前，需要完成以下环境准备：

系统要求检查清单：

• ✅ Python 3.11或更高版本
• ✅ ADB工具已安装并配置到PATH
• ✅ 至少一台Android设备已通过USB连接并启用调试模式
• ✅ 网络环境允许设备与主机通信

安装步骤：

# 1. 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/an/android-mcp-server.git cd android-mcp-server # 2. 使用uv安装Python环境（推荐） uv python install 3.11 uv sync # 3. 验证ADB连接 adb devices # 应显示类似：List of devices attached # emulator-5554 device

配置策略选择与实施

根据您的使用场景选择合适的配置策略：

场景1：单设备开发环境（推荐新手）

# 无需创建配置文件，系统自动检测唯一设备 python server.py

场景2：多设备测试环境

# 创建 config.yaml 文件 device: # 使用adb devices命令获取设备序列号 name: "emulator-5554" # 或实际设备序列号如 "13b22d7f"

场景3：混合环境灵活切换

# 使用环境变量动态配置 device: name: ${ANDROID_DEVICE_SERIAL:-null} # 优先使用环境变量，否则自动选择

Claude Desktop集成配置

Android MCP Server与Claude Desktop的集成配置是关键步骤：

1. 定位Claude Desktop配置文件

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

2. 编辑配置文件添加服务器

{ "mcpServers": { "android": { "command": "/path/to/uv", "args": [ "--directory", "/absolute/path/to/android-mcp-server", "run", "server.py" ] } } }

3. 配置验证与测试

# 验证服务器启动 cd /absolute/path/to/android-mcp-server uv run server.py # 重启Claude Desktop应用 # 在聊天界面测试工具可用性

高级配置：性能优化与自定义扩展

工具功能深度解析

Android MCP Server提供了5个核心工具，每个工具都有特定的使用场景和优化建议：

1. 应用包管理工具 (get_packages)

功能原理：通过ADB shell执行pm list packages命令，解析并返回设备上所有已安装的包名。

使用示例：

# 获取所有已安装应用包 packages = get_packages() # 返回格式：每行一个包名 # com.android.chrome # com.google.android.youtube # com.tencent.mm

性能优化建议：

• 缓存结果减少重复查询
• 使用过滤参数只获取特定应用
• 定期更新缓存避免信息过期

2. ADB命令执行工具 (execute_adb_shell_command)

功能原理：封装ADB shell命令执行，支持所有标准的ADB命令。

使用场景对比表：

安全注意事项：

• 避免执行高危命令如rm -rf /
• 验证用户输入防止命令注入
• 限制执行时间避免阻塞

3. UI布局分析工具 (get_uilayout)

功能原理：使用uiautomator dump获取当前界面XML，解析可点击元素信息。

返回数据结构：

Clickable element: Text: 登录 Description: 登录按钮 Bounds: [120,450][360,520] Center: (240, 485) Clickable element: Text: 注册 Description: 注册新账户 Bounds: [380,450][620,520] Center: (500, 485)

应用场景：

• 自动化测试脚本编写
• 界面元素定位与分析
• 无障碍功能开发辅助

4. 屏幕截图工具 (get_screenshot)

技术实现流程：

压缩策略说明：

• 原始分辨率降低到30%大小
• PNG格式，质量85%，启用优化
• 避免Claude Desktop的"maximum call stack exceeded"错误

5. 应用意图分析工具 (get_package_action_intents)

功能原理：解析dumpsys package输出，提取Activity Resolver Table中的非数据动作。

返回示例：

[ "android.intent.action.MAIN", "android.intent.action.VIEW", "com.example.app.CUSTOM_ACTION" ]

使用价值：

• 了解应用支持的操作类型
• 自动化测试中的意图触发
• 应用间通信分析

性能优化配置指南

连接稳定性优化

配置建议：

# 高级配置示例 device: name: "emulator-5554" connection: timeout: 30 # 连接超时时间（秒） retry_count: 3 # 连接重试次数 keep_alive: true # 保持长连接

环境变量优化：

# 设置ADB环境变量提升性能 export ADB_TRACE=all # 启用详细日志 export ADB_LOCAL_TRANSPORT_MAX=4 # 增加传输线程 export ADB_SERVER_SOCKET=tcp:5037 # 使用TCP连接

内存与资源管理

截图优化策略：

# 自定义截图压缩参数 def take_screenshot(self, quality=85, scale=0.3): """可配置的截图方法""" self.device.shell("screencap -p /sdcard/screenshot.png") self.device.pull("/sdcard/screenshot.png", "screenshot.png") with PILImage.open("screenshot.png") as img: width, height = img.size new_width = int(width * scale) new_height = int(height * scale) resized_img = img.resize( (new_width, new_height), PILImage.Resampling.LANCZOS ) resized_img.save( "compressed_screenshot.png", "PNG", quality=quality, optimize=True )

自定义工具扩展方法

添加新的ADB命令工具

步骤1：在server.py中添加新工具

@mcp.tool() def get_device_info() -> dict: """ 获取设备详细信息 Returns: dict: 包含设备信息的字典 """ # 获取设备型号 model = deviceManager.execute_adb_shell_command("getprop ro.product.model") # 获取Android版本 version = deviceManager.execute_adb_shell_command("getprop ro.build.version.release") # 获取设备序列号 serial = deviceManager.execute_adb_shell_command("getprop ro.serialno") return { "model": model.strip(), "android_version": version.strip(), "serial": serial.strip() }

步骤2：在AdbDeviceManager中添加对应方法

def get_device_info(self) -> dict: """获取设备详细信息""" commands = { "model": "getprop ro.product.model", "version": "getprop ro.build.version.release", "serial": "getprop ro.serialno", "manufacturer": "getprop ro.product.manufacturer" } result = {} for key, cmd in commands.items(): output = self.device.shell(cmd).strip() result[key] = output return result

创建复合工具

示例：应用安装状态检查工具

@mcp.tool() def check_app_status(package_name: str) -> dict: """ 检查应用安装与运行状态 Args: package_name: 应用包名 Returns: dict: 包含安装状态和运行状态的信息 """ # 检查是否安装 installed = deviceManager.is_package_installed(package_name) # 检查是否正在运行 running = deviceManager.is_package_running(package_name) # 获取应用信息 info = deviceManager.get_package_info(package_name) if installed else {} return { "package_name": package_name, "installed": installed, "running": running, "version": info.get("version", "N/A"), "last_update": info.get("last_update", "N/A") }

常见问题排查指南

连接问题诊断

问题1：ADB设备未识别

# 诊断步骤 adb devices # 检查设备列表 adb kill-server # 重启ADB服务 adb start-server # 启动ADB服务 adb devices # 重新检查 # 如果设备仍不显示，检查： # 1. USB调试是否启用 # 2. USB线缆是否正常 # 3. 设备是否授权此电脑

问题2：多设备连接冲突

错误信息：Multiple devices connected: ['device1', 'device2'] 解决方案： 1. 创建config.yaml指定设备 2. 断开不需要的设备 3. 使用环境变量动态选择

性能问题优化

截图速度慢的解决方案：

1. 降低截图分辨率：修改scale参数为0.2
2. 启用硬件加速：确保ADB使用TCP连接
3. 缓存截图结果：避免频繁重复截图

内存占用过高处理：

# 在AdbDeviceManager中添加清理方法 def cleanup_temp_files(self): """清理临时文件""" temp_files = ["screenshot.png", "compressed_screenshot.png", "window_dump.xml"] for file in temp_files: if os.path.exists(file): os.remove(file)

兼容性问题处理

不同Android版本的适配：

def get_android_version(self) -> int: """获取Android SDK版本用于兼容性判断""" version_str = self.device.shell("getprop ro.build.version.sdk") try: return int(version_str.strip()) except ValueError: return 21 # 默认最低支持版本

设备类型识别与适配：

def get_device_type(self) -> str: """识别设备类型（真机/模拟器）""" serial = self.device.serial if serial.startswith("emulator-"): return "emulator" elif ":" in serial: # 网络设备 return "network_device" else: return "physical_device"

安全最佳实践

命令执行安全

输入验证策略：

def safe_execute_command(self, command: str) -> str: """安全执行ADB命令""" # 禁止的危险命令列表 dangerous_commands = ["rm -rf", "dd if=", "chmod 777", "format"] for dangerous in dangerous_commands: if dangerous in command.lower(): raise ValueError(f"Dangerous command detected: {dangerous}") # 执行命令 return self.device.shell(command)

权限最小化原则：

• 避免使用root权限执行命令
• 限制可执行的命令范围
• 记录所有执行的命令日志

配置文件安全

敏感信息保护：

# 使用环境变量替代硬编码 device: name: ${ANDROID_DEVICE_SERIAL} # 或使用外部配置文件 import os device_name = os.getenv("ANDROID_DEVICE_SERIAL", "default_device")

测试与验证策略

单元测试编写

设备管理器测试示例：

# tests/test_custom_tools.py def test_get_device_info(): """测试设备信息获取功能""" with patch('adbdevicemanager.AdbClient') as mock_client: mock_device = MagicMock() mock_device.shell.side_effect = [ "Pixel 7", # model "14", # android version "ABC123DEF456" # serial ] mock_client.return_value.device.return_value = mock_device manager = AdbDeviceManager(device_name="test-device", exit_on_error=False) info = manager.get_device_info() assert info["model"] == "Pixel 7" assert info["version"] == "14" assert info["serial"] == "ABC123DEF456"

集成测试流程

端到端测试脚本：

# tests/test_integration.py def test_complete_workflow(): """测试完整工作流程""" # 1. 初始化服务器 server = start_mcp_server() # 2. 连接设备 device_info = server.get_device_info() assert device_info["connected"] == True # 3. 执行截图 screenshot = server.get_screenshot() assert screenshot is not None # 4. 分析UI布局 ui_layout = server.get_uilayout() assert "Clickable element" in ui_layout # 5. 清理资源 server.cleanup()

部署与监控

生产环境部署

Docker容器化部署：

# Dockerfile FROM python:3.11-slim # 安装ADB RUN apt-get update && apt-get install -y \ android-tools-adb \ && rm -rf /var/lib/apt/lists/* # 复制项目文件 WORKDIR /app COPY . . # 安装Python依赖 RUN pip install uv RUN uv sync --frozen # 暴露端口 EXPOSE 8000 # 启动命令 CMD ["uv", "run", "server.py"]

系统服务配置：

# /etc/systemd/system/android-mcp.service [Unit] Description=Android MCP Server After=network.target [Service] Type=simple User=android-user WorkingDirectory=/opt/android-mcp-server Environment=ANDROID_DEVICE_SERIAL=emulator-5554 ExecStart=/usr/local/bin/uv run server.py Restart=on-failure [Install] WantedBy=multi-user.target

监控与日志

结构化日志配置：

import logging import json # 配置结构化日志 logging.basicConfig( level=logging.INFO, format='{"time": "%(asctime)s", "level": "%(levelname)s", "module": "%(name)s", "message": "%(message)s"}' ) logger = logging.getLogger(__name__) # 在关键操作中添加日志 def execute_adb_shell_command(self, command: str) -> str: logger.info({ "action": "execute_adb_command", "command": command, "device": self.device.serial }) try: result = self.device.shell(command) logger.info({ "action": "adb_command_success", "command": command, "result_length": len(result) }) return result except Exception as e: logger.error({ "action": "adb_command_failed", "command": command, "error": str(e) }) raise

通过以上配置和优化，Android MCP Server可以在各种环境中稳定运行，为AI助手提供强大的Android设备控制能力。无论是单设备开发环境还是多设备测试集群，都能通过灵活的配置和扩展满足不同的自动化需求。

【免费下载链接】android-mcp-serverAn MCP server that provides control over Android devices via adb项目地址: https://gitcode.com/gh_mirrors/an/android-mcp-server