admcp - Android Debug MCP

admcp

admcp 是一款本地优先的 Android 开发模型上下文协议（MCP）服务。它可将任意 MCP stdio 客户端连接到真实设备或模拟器，并提供 51 个类型化工具，用于 UI 检查、屏幕截图、logcat、Java/Kotlin JDI 调试、原生 LLDB、Flutter/Dart DAP、Compose 检查、Perfetto 跟踪、堆转储、工件和基于证据的诊断。

无需 root。无需云账户。

快速开始 | 功能 | 示例提示词 | 为什么选择 admcp | 文档

状态：v1，提供 51 个工具，已在 OnePlus CPH2747（API 36，arm64-v8a）上实测。 完整证据和剩余限制： 实现状态。

快速开始

1. 安装 JDK 21 和 Android SDK platform-tools（adb）。
2. 从 GitHub Releases 下载 admcp-<version>.zip 并解压。兼容 MCPB 的客户端也可以从同一发布版本安装 admcp-<version>.mcpb。
3. 在 Windows 上将 MCP 客户端指向 bin/admcp.bat，在 Linux 和 macOS 上指向 bin/admcp。

任何 MCP stdio 客户端都可以使用它。以下 JSON 使用常见的 mcpServers 格式；请根据你的客户端（Claude Code、Cursor、VS Code、Codex、Gemini CLI 等）调整命令和参数。

{
  "mcpServers": {
    "admcp": {
      "command": "C:\\Tools\\admcp\\admcp-<version>\\bin\\admcp.bat",
      "args": [
        "--platform-tools", "C:\\Android\\Sdk\\platform-tools",
        "--artifacts", "C:\\temp\\admcp-artifacts"
      ]
    }
  }
}

在 Linux 和 macOS 上，将 /opt/admcp/admcp-<version>/bin/admcp 用作 command。

验证安装：

C:\Tools\admcp\admcp-<version>\bin\admcp.bat --selftest

在 Linux 和 macOS 上：

/opt/admcp/admcp-<version>/bin/admcp --selftest

你应该会在 stderr 中看到 catalog=51 registered=51 version=<version>。随后，服务会通过 stdio 使用 MCP 通信；stdout 专用于协议流量。

功能

完整的 51 个工具契约见 docs/architecture/mcp-tool-catalog-v1.md。 目录通过契约测试进行验证。

示例提示词

连接 admcp 后，可以向你的 Agent 提出类似这样的问题：

Inspect the current screen, find the INCREMENT button, tap it, and verify the counter changed.
Start logcat, reproduce the crash, then summarize the stack trace and the last 50 lines before it.
Launch the app, attach JDI, set a breakpoint in MainActivity, and show locals when it hits.
Inspect this Compose screen and tell me which accessibility node is the DELETE COUNTER button.
Record a 5-second Perfetto trace and summarize what happened.
Attach LLDB to the native library, break in fixture_increment, and show the registers.

为什么选择 admcp

许多 Android MCP 工具只是简单的命令包装器。admcp 将设备、工作区、 进程和会话状态整合在一起，然后通过带类型的架构、产物和安全门提供 调试基础操作。

适用于：

• 希望 Claude Code、Cursor 或其他 Agent 检查并调试真实设备的 Android 开发者。
• 需要稳定、带类型的 Android 操作，而不是解析 adb 字符串的 Agent 构建者。
• 需要从设备获取可复现证据的 QA 和自动化工作流。

对于坐在 IDE 前的开发者，Android Studio 是更好的工具。admcp 面向需要检查、 操作和调试，且不想让人类驱动每次点击的 Agent。

工作原理

flowchart LR
    Client["MCP client / agent"] -->|stdio| Server["admcp (MCP server)"]
    Server --> ADB["ADB / Android CLI"]
    Server --> JDI["JDI (JDWP client)"]
    Server --> LLDB["lldb-dap"]
    Server --> DAP["Flutter DAP"]
    ADB --> Device["Android device / emulator"]
    JDI -.->|via adb forward| ADB
    LLDB -.->|via adb forward / lldb-server| ADB
    DAP -.->|via adb forward| ADB

服务在你的计算机上与 Android 工具链并行运行。它不会将你的项目或设备数据 上传到任何地方。

已验证

• 在已验证的主机上运行了 186 项测试，0 项失败。
• 目录通过 MCP stdio 注册了全部 51 个工具。
• 实时设备：OnePlus CPH2747，API 36，arm64-v8a。
• JDI：附加、断点、单步执行、堆栈、局部变量和只读求值。
• LLDB：附加、断点、堆栈、寄存器、有限内存读取和模块。
• Flutter：DART_DAP 断点、堆栈、变量、单步执行、暂停和分离。
• Compose：无障碍树检查和经过验证的 UI 操作。
• 性能：Perfetto 捕获/分析和 HPROF 堆转储捕获。
• 证据：logcat、崩溃缓冲区、产物、会话时间线和诊断信息。

未连接设备时，依赖设备的集成测试会跳过。完整的验收证据请参阅 实现状态。

要求

• JDK 21。
• Android SDK platform-tools（adb）。
• Windows、Linux 或 macOS。
• 可选：Android CLI、Flutter SDK、NDK lldb/lldb-server、lldb-dap，以及 已连接的设备或模拟器。

仅支持可调试的开发版本。不在支持范围内的包括 root 和绕过 Android 安全机制。

从源代码构建

gradlew.bat clean test
gradlew.bat :app:admcp:installDist

./gradlew clean test
./gradlew :app:admcp:installDist

配置

workspace_trust 仅在传给服务启动参数 --trust-workspace 的规范根目录下成功。工具参数 不能自行声明已获批准。

已知限制

• 已验证的设备是运行 API 36 的 OnePlus CPH2747；不保证支持其他 OEM、API 和传输方式组合。
• 在已验证的设备上，同时使用 JDI 和 LLDB 检查并不可靠。使用 debug_attach(switchBackend=true) 可顺序切换。
• Compose TREE 使用无障碍层级。内部语义、slot 表和重组数据需要对应用进行插桩。
• 未捆绑主机端 trace_processor_shell，因此除非安装 Perfetto SQL 工具，否则跟踪分析只会返回有限摘要。
• Crashlytics 问题集群需要运行 android auth login；本地崩溃缓冲区仍是默认的证据来源。
• 原生 LLDB 需要单独安装 lldb-dap 和 ABI 匹配的 lldb-server。
• 主机确认对话框需要交互式桌面。无头服务器会安全地拒绝操作，并改用一次性令牌。

详情和确切的错误行为请参阅实现状态。

安全

• 仅支持可调试的开发版本。
• 只有在明确授予工作区信任后，才会运行由项目控制的代码。
• 破坏性 UI 操作需要主机确认，或使用绑定到会话和操作的一次性令牌。
• 工件读取仅限于存储根目录，默认设有大小上限并进行脱敏。
• 此 MCP 服务以本地优先：不需要云帐户。

文档

• 技术设计
• 实现状态
• 工具目录（Markdown）
• 工具目录（JSON）
• 发布到 MCP Registry

贡献

欢迎提交问题和拉取请求。公开工具目录采用版本管理；添加或重命名公开工具前，请先提交问题。发送 PR 前运行 gradlew test。

如果 admcp 能为你的 Agent 节省时间，请点个星，帮助更多 Android 开发者发现它。

许可证

Apache License 2.0。请参阅 LICENSE。