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).