adbmcp 是一个模型上下文协议服务器，它暴露了 Android 调试桥（[adb）与 AI 代理：列出设备、运行 shell 命令、安装应用、读取 logcat，截图，驱动界面（点选/滑动/打字/按键事件），查询系统服务 dumpsys，传输文件，转发端口，管理应用权限，并通过 Wi-Fi。它是一个薄薄、可预测的包裹，包裹着官员 adb 二进制——没有重新实现的adb协议，没有测试框架，没有额外的状态。

• 多设备优先 — 每个设备范围工具都选择一个可选的device序列号和每个adb 调用的范围是adb -s ;歧义是候选对象的错误。
• 代理可采取行动的失败 — adb stderr/exit 代码映射到类型化的原因 （NO_DEVICE， MULTIPLE_DEVICES， DEVICE_UNAUTHORIZED、DEVICE_OFFLINE、ADB_SERVER_CONFLICT， TIMEOUT， COMMAND_FAILED）并提示下一步。
• 安全结构化 — 每个工具及服务器端护栏均有完整的MCP注释， 即使主机忽略注释，也被强制执行。
• stdio默认，可流式HTTP可选——客户端作为子进程启动adbmcp;

adbmcp — Android Debug Bridge, as MCP tools

adbmcp is a Model Context Protocol server that exposes the Android Debug Bridge (adb) to AI agents: list devices, run shell commands, install apps, read logcat, take screenshots, drive the UI (tap/swipe/type/key events), query system services with dumpsys, transfer files, forward ports, manage app permissions and pair/connect to devices over Wi-Fi. It is a thin, predictable wrapper around the official adb binary — no re-implemented adb protocol, no test framework, no extra state.

• Multi-device first — every device-scoped tool takes an optional device serial and every adb call is scoped with adb -s ; ambiguity is an error listing the candidates.
• Failures an agent can act on — adb stderr/exit codes are mapped to typed causes (NO_DEVICE, MULTIPLE_DEVICES, DEVICE_UNAUTHORIZED, DEVICE_OFFLINE, ADB_SERVER_CONFLICT, TIMEOUT, COMMAND_FAILED) with a hint for the next step.
• Safety by construction — full MCP annotations on every tool plus server-side guardrails that are enforced even if a host ignores annotations.
• stdio by default, Streamable HTTP optional — the client launches adbmcp as a subprocess; --http serves the same tools over /mcp for shared-device-host deployments.

Implements the MVP plus v2.0 items 1–7 in docs/design/product-design-v0.md.

Install

Requires Node.js >= 20 and Android platform-tools (adb) on PATH — or ADB_PATH pointing at the binary.

# from npm
npx -y @yhuangsh/adbmcp

# from a checkout
git clone https://github.com/yhuangsh/adbmcp.git && cd adbmcp
npm install
npm run build
node dist/index.js        # speaks MCP on stdin/stdout

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": ["-y", "adbmcp"],
      "env": {
        "ADB_PATH": "/Users/me/Library/Android/sdk/platform-tools/adb"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "adb": {
      "command": "node",
      "args": ["/absolute/path/to/adbmcp/dist/index.js"],
      "env": {
        "ADBMCP_ALLOWED_DEVICES": "emulator-5554"
      }
    }
  }
}

Other stdio clients work the same way: a command plus args, with ADB_PATH / ADBMCP_* environment variables passed through. In stdio mode, stdout carries MCP protocol traffic only; diagnostics go to stderr.

Streamable HTTP (shared device host)

Use HTTP when several agents or MCP clients should share one machine’s adb server, devices and