AI导哈

ADB MCP桥接工具

adb-mcp-bridge是一个本地MCP标准输入输出服务器，通过ADB为AI代理（如Codex和Claude）提供安全、结构化的Android模拟器访问。

  • by aerickson
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aerickson/adb_mcp_bridge

使用说明

adb-mcp桥

adb-mcp桥 是当地人 MCP（模型上下文协议）stdio服务器 这暴露了安全， 通过以下方式结构化访问Android模拟器 安卓调试桥 供AI代理使用，例如 法典 和 克劳德.

该项目侧重于安全性、确定性和干净的可扩展性。特工永远不会得到生壳 访问，所有设备状态都由网桥而不是模型管理。

特性

v1.0

  • 从正在运行的Android模拟器中截取屏幕截图
  • 单设备支持
  • 仅模拟器执行(emulator-*)
  • 结构化MCP工具界面
  • 默认情况下安全（无任意 adb shell)

计划（v1.0+）：

  • 多设备支持
  • UI交互（点击、滑动、输入）
  • UI检查（uiautomator转储）
  • 应用生命周期管理
  • 根据设备状态和锁定

需求

  • Python 3.10+
  • Android SDK adb 在你的路上
  • 至少一个正在运行的Android模拟器
  • 具有MCP功能的代理（Codex、Claude CLI等）

快速开始

git clone https://github.com/aerickson/adb_mcp_bridge.git
cd adb-mcp-bridge
make install

这将通过pipx安装服务器，并全局配置Codex和Claude CLI。

手动设置

安装服务器：

pipx install -e .

配置MCP客户端：

make install-codex
make install-claude-global

如果跳过Makefile，请手动配置MCP客户端（Codex/Claude CLI）。

笔记：

  • make install-claude-global 在用户范围内安装；删除与 make uninstall-claude-global.
  • make install 始终刷新pipx安装(pipx install -e . --force).

对于项目，在另一个仓库中本地安装（创建 .mcp.json 在该仓库中），运行：

claude mcp add-json --scope project adb_mcp_bridge '{"type":"stdio","command":"adb-mcp-bridge","args":[]}'

调试设置

make doctor

这将打印配置路径，解析 adb-mcp-bridge 从您的PATH，并显示 adb devices -l.

运行测试

uv sync --extra dev
uv run pytest

运行MCP服务器

adb-mcp-bridge

该过程作为 stdio MCP服务器 并等待来自代理的请求。

您可以通过以下方式检查已安装的版本：

adb-mcp-bridge --version

MCP工具：take_screenshot

从活动的Android模拟器中捕获PNG屏幕截图。

输入

  • output_dir （可选，默认 ./screenshots)
  • include_base64 （可选，默认 false)

输出

  • path –PNG的文件系统路径
  • bytes –文件大小
  • timestamp –unix时间戳
  • mime_type – image/png
  • base64_png –可选的base64图像数据

如果出现以下情况，该工具将失败：

  • 没有可用的设备，
  • 连接了多个设备，
  • 该设备不是仿真器，
  • 设备离线或未经授权。

与Codex一起使用

将服务器添加到Codex MCP配置中(~/.codex/config.toml):

[mcp_servers.adb_mcp_bridge]
command = "adb-mcp-bridge"
args = []
startup_timeout_sec = 20
tool_timeout_sec = 60

重新启动Codex和 take_screenshot 工具将可用。

使用Claude CLI

Claude CLI从以下位置加载MCP服务器 .mcp.json 在项目根中。 使用 make install-claude 要添加此服务器，请运行 claude mcp list 以验证。

使用MCP工具

配置MCP服务器（Codex或Claude CLI）后，您可以调用 take_screenshot 工具。它只接受关键字参数：

{
  "output_dir": "./screenshots",
  "include_base64": false
}

笔记：

  • 主动设备是自动选择的；必须连接一个仿真器。
  • 如果找不到设备、连接了多个设备或设备脱机/未经授权，则返回错误。

示例提示：

  • Use the take_screenshot tool.
  • Use the take_screenshot tool with output_dir set to ./screenshots and include_base64 false.

安全模型

  • 仅限显式工具接口
  • 无原始shell执行
  • 默认情况下仅限模拟器
  • 亚行所有业务暂停
  • 确定性、结构性错误

项目状态

  • 状态： 早期发育
  • 当前版本： 1.0.0（仅截图）
  • API稳定性： 实验性

许可证

Mozilla公共许可证v2.0（请参阅 LICENSE).

相关 MCP