admcp - Android Debug MCP

admcp

admcp is a local-first Model Context Protocol (MCP) server for Android development. It connects any MCP stdio client to a real device or emulator and exposes 51 typed tools for UI inspection, screenshots, logcat, Java/Kotlin JDI debugging, native LLDB, Flutter/Dart DAP, Compose inspection, Perfetto traces, heap dumps, artifacts and evidence-based diagnostics.

No root. No cloud account required.

Quick start | What it can do | Example prompts | Why admcp | Documentation

Status: v1, 51 tools, live-tested on a OnePlus CPH2747 (API 36, arm64-v8a).

Full evidence and remaining limits:

implementation status.

Quick start

1. Install JDK 21 and Android SDK platform-tools (adb).
2. Download admcp- .zip from GitHub Releases and unzip it. MCPB-compatible clients can install admcp- .mcpb from the same release instead.
3. Point your MCP client at bin/admcp.bat on Windows or bin/admcp on Linux and macOS.

Any MCP stdio client can use it. The JSON below uses the common mcpServers shape; adapt the command and arguments to your client (Claude Code, Cursor, VS Code, Codex, Gemini CLI, and similar).

{

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

On Linux and macOS, use /opt/admcp/admcp- /bin/admcp as command.

Verify the install:

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

On Linux and macOS:

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

You should see catalog=51 registered=51 version= on stderr. The server then speaks MCP over stdio; stdout is reserved for protocol traffic.

What it can do

The full 51-tool contract is in docs/architecture/mcp-tool-catalog-v1.md. The catalog is validated by contract tests.

Example prompts

Once admcp is connected, ask your agent things like:

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.

Why admcp

Many Android MCP tools are thin command wrappers. admcp keeps device, workspace, process and session state together, then exposes debugging primitives with typed schemas, artifacts and safety gates.

It is for:

• Android developers who want Claude Code, Cursor or another agent to inspect and debug a real device.
• Agent builders who need stable, typed Android actions instead of parsing adb strings.
• QA and automation workflows that need reproducible evidence from a device.

Android Studio is the better tool for a human sitting at the IDE. admcp is for the agent that needs to inspect, act and debug without a human driving every click.

How it works

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

The server runs on your machine next to the Android toolchain. It does not upload your project or device data anywhere.

Verified

• 186 tests with 0 failures on the verified host.
• The catalog registers all 51 tools over MCP stdio.
• Live device: OnePlus CPH2747, API 36, arm64-v8a.
• JDI: attach, breakpoints, step, stack, locals and read-only evaluation.
• LLDB: attach, breakpoints, stack, registers, bounded memory reads and modules.
• Flutter: DART_DAP breakpoints, stack, variables, step, pause and detach.
• Compose: accessibility-tree inspection and verified UI actions.
• Performance: Perfetto capture/analysis and HPROF heap-dump capture.
• Evidence: logcat, crash buffer, artifacts, session timeline and diagnostics.

Device-dependent integration tests skip when no device is attached. See implementation status for the full acceptance evidence.

Requirements

• JDK 21.
• Android SDK platform-tools (adb).
• Windows, Linux or macOS.
• Optional: Android CLI, Flutter SDK, NDK lldb/lldb-server, lldb-dap and a connected device or emulator.

Only debuggable developer builds are supported. Root and Android security bypasses are out of scope.

Build from source

Build, test and package from source

The Gradle wrapper is checked in; no local Gradle install is required.

Windows:

gradlew.bat clean test

gradlew.bat :app:admcp:installDist

Linux and macOS:

./gradlew clean test

./gradlew :app:admcp:installDist

The installable distribution is written to app/admcp/build/install/admcp/. The release archive is built with :app:admcp:distZip and written to app/admcp/build/distributions/admcp- .zip.

Releases are automated with semantic-release from Conventional Commits on pushes to main or master: fix: is a patch release, feat: is a minor release and BREAKING CHANGE: is a major release. No release PR or changelog is generated.

Configuration

workspace_trust only succeeds for a canonical root passed to the server at startup with --trust-workspace. A tool argument cannot self-assert approval.

Known limitations

• The verified device is a OnePlus CPH2747 on API 36; other OEM, API and transport combinations are not claimed.
• Simultaneous JDI and LLDB inspection is not reliable on the verified device. Sequential switching works with debug_attach(switchBackend=true).
• Compose TREE uses the accessibility hierarchy. Internal semantics, slot table and recomposition data require app instrumentation.
• No host trace_processor_shell is bundled, so trace analysis returns a bounded summary unless Perfetto SQL tooling is installed.
• Crashlytics issue clusters require android auth login; the local crash buffer remains the default evidence source.
• Native LLDB needs a separately installed lldb-dap and an ABI-matched lldb-server.
• The host confirmation dialog requires an interactive desktop. Headless servers fail closed to a one-shot token.

See implementation status for details and exact error behavior.

Security

• Only debuggable developer builds are supported.
• Project-controlled code runs only after an explicit workspace trust grant.
• Destructive UI actions require host confirmation or a one-shot token bound to the session and action.
• Artifact reads are confined to the store root, capped and redacted by default.
• The server is local-first: no cloud account is required.

Documentation

• Technical design
• Implementation status
• Tool catalog (Markdown)
• Tool catalog (JSON)
• MCP Registry publishing

Contributing

Issues and pull requests are welcome. The public tool catalog is versioned; open an issue before adding or renaming a public tool. Run gradlew test before sending a PR.

If admcp saves your agent time, a star helps more Android developers find it.

License

Apache License 2.0. See LICENSE.