Agent Droid Bridge

Agent Droid Bridge

Agent Droid Bridge 是一个 MCP 服务，可通过 ADB 将 AI Agent 连接到 Android 设备和模拟器。它专为移动自动化、应用测试、动态分析和逆向工程打造：将 ADB 的全部功能封装为结构化工具，供任何兼容 MCP 的 AI 客户端直接调用。只要 ADB 能做到，Agent 就能做到。

---

专用工具会返回精简的结构化响应。不输出原始 XML 转储，不浪费上下文——让 Agent 在长会话中始终保持快速。

演示

上方的演示通过几个简单任务展示已连接的 Agent 可以做什么，而这仅仅是冰山一角：

• 安装 Paint 应用，打开应用，并通过计算墙壁和屋顶的像素坐标画一栋房子
• 打开设备浏览器，搜索“ M C P Wikipedia ”，进入结果页面并截取屏幕截图
• 打开 Calculator，计算 1337 × 42，并将结果提取到主机
• 打开 Contacts，创建包含姓名和电话号码的新联系人，并确认已保存
• 打开 Calendar 并为指定日期安排约会
• 打开 Settings 并切换深色模式
• 从设备中提取 Calculator APK 到主机
• 安装 Notepad，撰写一句话总结所有已完成的任务，并截取最后的屏幕截图

功能

工具

• 14 个内置工具，用于屏幕捕获、UI 检查、文本读取、元素提取、触摸和滑动输入、文本输入、键码事件、应用启动、ADB 命令和设备检查
• app_manager 工具包新增 9 个工具，用于软件包管理、应用生命周期管理、APK 提取、权限管理和 Intent 注入。通过 ADB_EXTRA_TOOL_PACKS=app_manager 加载
• 工具可用性会反映在服务的启动说明中。Agent 在连接时会收到准确的工具目录

设备处理

• 自动检测单台已连接设备；存在多台设备时会提示选择
• 通过标准输入/输出运行，兼容任何支持 MCP 的 AI 客户端
• 返回结构化响应，而非原始 XML 转储，让 Agent 在长时间自动化运行中保持精简上下文

安全

• 两种执行模式：unrestricted（完整 ADB 访问权限，可选拒绝列表）和 restricted（仅允许列表，阻止所有未明确许可的操作）
• 设置 ADB_ALLOW_SHELL=false 可在任何模式下禁用所有 shell 命令
• 使用 ADB_DENIED_TOOLS 对 Agent 隐藏特定工具
• 所有命令均通过 shlex 解析，不可能发生 shell 注入

可观测性

• 可选的会话记录器会将每次工具调用、ADB 命令和安全事件记录到结构化 JSONL 文件中。通过 MCP_LOG_ENABLED=true 和 MCP_LOG_DIR 启用

使用场景

移动端 QA 和测试自动化 无需修改应用或编写测试代码，即可在真机和模拟器上自动化 UI 流程。通过自然语言提示词完成点击、滑动、输入、读取屏幕内容和截屏。

应用安全研究 提取 APK、检查声明的权限、发送任意 Intent，并观察屏幕上的运行时行为。无需插桩或越狱。

动态分析 在受控状态下启动应用、执行 UI 交互、捕获每个步骤的屏幕状态并提取产物，所有操作都可通过 AI Agent 编写脚本。

开发与调试 无需离开编码环境即可安装构建版本、验证 UI 状态、检查应用信息并运行 ADB 命令。

安装

uvx agent-droid-bridge

无需克隆代码库或创建虚拟环境。需要 Python 3.11+，并在主机上安装 ADB。

uvx 由 uv 提供。如果尚未安装：curl -LsSf https://astral.sh/uv/install.sh | sh

如需改为从源代码安装，请参阅 docs/setup.md — Option B。

验证安装：uvx agent-droid-bridge --help

快速开始

1. 安装 ADB — 平台专属说明请参阅 docs/setup.md
2. 连接 Android 设备或启动模拟器
3. 将服务添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "agent-droid-bridge": {
      "command": "uvx",
      "args": ["agent-droid-bridge"],
      "env": {
        "ADB_EXECUTION_MODE": "unrestricted",
        "ADB_ALLOW_SHELL": "true",
        "ADB_PATH": "adb",
        "ADB_EXTRA_TOOL_PACKS": "",
        "MCP_LOG_ENABLED": "false",
        "MCP_LOG_DIR": "~/logs/agent-droid-bridge"
      }
    }
  }
}

如需启用会话日志记录，请将 MCP_LOG_ENABLED 设为 "true"，并将 MCP_LOG_DIR 更新为计算机上可写入的路径。

变量	默认值	说明
ADB_EXECUTION_MODE	unrestricted	安全模式。unrestricted 允许所有 shell 命令（可选拒绝列表）；restricted 仅允许 ADB_SHELL_ALLOWLIST 中的命令。
ADB_ALLOW_SHELL	true	设为 false 可在任何执行模式下阻止所有 adb shell 命令。
ADB_PATH	adb	ADB 二进制文件的路径。如果 adb 不在系统 PATH 中，请替换为完整路径（例如 Windows 上的 C:\platform-tools\adb.exe）。
ADB_EXTRA_TOOL_PACKS	(empty)	要加载的额外工具包列表，以逗号分隔。设为 app_manager 可启用额外的 9 个应用管理工具。
MCP_LOG_ENABLED	false	设为 true 可启用会话日志记录。需要设置 MCP_LOG_DIR。
MCP_LOG_DIR	(none)	写入会话日志的目录。MCP_LOG_ENABLED 为 true 时必填。

4. 提示 Agent 使用 agent-droid-bridge MCP 工具

完整的设置指南和环境变量参考：docs/setup.md

工具

工具	功能
get_ui_hierarchy	以 XML UI 层级结构的形式返回当前屏幕内容
take_screenshot	将屏幕截图编码为 base64 格式的 PNG
tap_screen	在像素坐标处发送点击手势
swipe_screen	在给定时长内，在两点之间发送滑动手势
type_text	在当前聚焦的输入框中输入文本
press_key	发送 Android 键码事件（返回、主页、回车等）
launch_app	通过 package/activity 组件名称启动应用
execute_adb_command	运行任意 ADB 或 ADB shell 命令
list_devices	列出 ADB 当前可见的所有 Android 设备及其序列号、状态和型号
snapshot_ui	获取轻量级 UI 快照，并返回一个供 detect_ui_change 使用的令牌
detect_ui_change	在执行操作后轮询 UI 变化；接受快照令牌作为基线；仅在请求时返回层级结构
get_screen_elements	解析 UI 层级结构，并返回包含坐标和交互属性的结构化元素；支持 tappable、interactive、input 和 all 模式
get_screen_text	以纯文本形式返回屏幕上所有可见文本，并按从上到下的顺序排列
check_device_capabilities	在一次调用中返回结构化的设备信息，包括身份、安全状况和硬件规格；支持 identity、security、hardware 和 all 模式

额外工具包

可选工具包可扩展核心工具集。在 MCP 客户端配置中设置 ADB_EXTRA_TOOL_PACKS 即可启用。请参阅 docs/extra-tool-packs.md。

app_manager

包管理、应用生命周期控制、APK 提取、权限管理和 Intent 注入。

工具	功能说明
list_packages	列出已安装的软件包，支持可选筛选、搜索和详细程度设置
get_app_info	返回单个已安装应用的完整静态元数据
install_app	将主机路径中的 APK 安装到设备上
uninstall_app	按软件包名称移除已安装的应用
pull_apk	将设备上的已安装 APK 提取到主机
manage_permission	授予、撤销、检查或列出应用的运行时权限
launch_app_extra	按软件包名称启动应用，并自动解析启动器 Activity
manage_app	控制应用运行时状态——停止、清除数据、清除缓存、启用、停用
inject_intent	通过 am start、am broadcast 或 am startservice 向组件发送 Intent

完整参数参考：docs/tools.md

配置

完全通过 MCP 客户端的 env 块配置服务。无需编辑任何文件。上方快速入门中的 env 块涵盖了最常用的设置。有关完整参考，包括安全筛选、工具可见性和超时设置，请参阅 docs/configuration.md。

如需改用 YAML 配置文件，请设置 ADB_CONFIG_SOURCE=yaml。详情请参阅 docs/configuration.md。

会话记录需单独配置。使用 MCP_LOG_ENABLED=true 和 MCP_LOG_DIR 启用。完整参考：docs/logging.md。

文档

文件	描述
docs/setup.md	前置条件、安装和 MCP 客户端配置
docs/tools.md	所有工具的完整参数参考
docs/configuration.md	环境变量和 adb_config.yaml 参考
docs/logging.md	会话记录器——日志文件、级别、保留期限和启用方式
docs/extra-tool-packs.md	额外工具包——启用工具包、工具包约定和编写自定义工具包
docs/troubleshooting.md	常见设置问题和 ADB 故障
docs/workflows.md	常见多工具工作流示例
CHANGELOG.md	发布历史和版本变更

贡献

欢迎贡献。有关设置、代码规范和提交拉取请求的指南，请参阅 CONTRIBUTING.md。

如需报告安全漏洞，请遵循 SECURITY.md 中的流程——请勿公开提交问题。