Android MCP Server3步实现AI驱动的Android设备自动化控制【免费下载链接】android-mcp-serverAn MCP server that provides control over Android devices via adb项目地址: https://gitcode.com/gh_mirrors/an/android-mcp-serverAndroid 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友好的工具接口。项目架构基于三层设计MCP协议层处理与客户端的标准通信协议业务逻辑层封装Android设备的核心操作功能ADB连接层通过pure-python-adb库与设备建立连接设备连接管理策略设备连接是本项目的关键特性支持多种配置模式配置模式适用场景配置方法优势自动选择模式单设备开发环境无需配置文件或设置device.name: null零配置开箱即用手动指定模式多设备测试环境在config.yaml中指定设备序列号精确控制避免设备冲突动态检测模式设备频繁切换通过代码动态检测设备列表灵活适应变化环境设备连接的核心逻辑位于adbdevicemanager.py的AdbDeviceManager类中。当初始化时系统会检查ADB环境是否就绪获取当前连接的设备列表根据配置策略选择目标设备建立稳定的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(fDevice {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的集成配置是关键步骤定位Claude Desktop配置文件Windows:%APPDATA%\Claude\claude_desktop_config.jsonmacOS:~/Library/Application Support/Claude/claude_desktop_config.json编辑配置文件添加服务器{ mcpServers: { android: { command: /path/to/uv, args: [ --directory, /absolute/path/to/android-mcp-server, run, server.py ] } } }配置验证与测试# 验证服务器启动 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命令。使用场景对比表命令类型示例命令返回内容适用场景系统信息adb shell getprop ro.build.version.sdkAndroid SDK版本设备兼容性检查文件操作adb shell ls /sdcard/目录列表文件管理进程管理adb shell ps进程列表应用状态监控网络诊断adb shell ping -c 4 8.8.8.8网络测试结果网络连接检查安全注意事项避免执行高危命令如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_TRACEall # 启用详细日志 export ADB_LOCAL_TRANSPORT_MAX4 # 增加传输线程 export ADB_SERVER_SOCKETtcp:5037 # 使用TCP连接内存与资源管理截图优化策略# 自定义截图压缩参数 def take_screenshot(self, quality85, scale0.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, qualityquality, optimizeTrue )自定义工具扩展方法添加新的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) }常见问题排查指南连接问题诊断问题1ADB设备未识别# 诊断步骤 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. 使用环境变量动态选择性能问题优化截图速度慢的解决方案降低截图分辨率修改scale参数为0.2启用硬件加速确保ADB使用TCP连接缓存截图结果避免频繁重复截图内存占用过高处理# 在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(fDangerous 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_nametest-device, exit_on_errorFalse) 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] DescriptionAndroid MCP Server Afternetwork.target [Service] Typesimple Userandroid-user WorkingDirectory/opt/android-mcp-server EnvironmentANDROID_DEVICE_SERIALemulator-5554 ExecStart/usr/local/bin/uv run server.py Restarton-failure [Install] WantedBymulti-user.target监控与日志结构化日志配置import logging import json # 配置结构化日志 logging.basicConfig( levellogging.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考