DeepADB

DeepADB

MCP (Model Context Protocol) server providing full Android Debug Bridge (ADB) integration for AI agents. Enables MCP clients to directly interact with connected Android devices — inspecting state, running commands, managing apps, capturing logs, controlling device settings, analyzing UI hierarchies, recording screens, managing emulators, running structured test sessions, orchestrating multi-device operations, capturing network traffic, running CI pipelines, auditing accessibility, detecting performance regressions, executing cloud device farm tests, debugging over WiFi, building projects, and managing community plugins.

204 tools, 5 resources, and 4 prompts across 45 modules — the most comprehensive ADB MCP server available, with triple transport (stdio + HTTP/SSE + WebSocket), optional GraphQL API, defense-in-depth security, modem firmware analysis, workflow marketplace, AT command interface with multi-chipset support, RIL message interception, device profiling, baseband/modem integration, automated test generation, OTA update monitoring, SELinux auditing, thermal/power profiling, network device discovery, visual regression detection, workflow orchestration, accessibility auditing, and contextual truncation.

Architecture

┌──────────────────────────────────────────────────┐
│                   MCP Client                     │
│             (Claude Code / claude.ai)            │
└──────────────────────┬───────────────────────────┘
                       │ stdio (JSON-RPC) or HTTP/SSE or WebSocket
┌──────────────────────▼───────────────────────────┐
│               DeepADB Server                     │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Tool Modules (45)                 │ │
│  │  device │ shell │ packages │ files │ logs   │ │
│  │  diagnostics │ ui │ build │ health          │ │
│  │  wireless │ control │ logcat-watch          │ │
│  │  forwarding │ screen-record │ emulator      │ │
│  │  testing │ multi-device │ snapshot          │ │
│  │  network-capture │ ci │ plugins │ baseband  │ │
│  │  accessibility │ regression                 │ │
│  │  device-farm │ registry │ at-commands       │ │
│  │  screenshot-diff │ workflow │ sensors       │ │
│  │  split-apk │ mirroring │ test-gen           │ │
│  │  ota-monitor │ ril-intercept                │ │
│  │  device-profiles │ firmware-analysis        │ │
│  │  workflow-market │ selinux-audit            │ │
│  │  thermal-power │ network-discovery          │ │
│  │  input-gestures │ wireless-firmware         │ │
│  ├─────────────────────────────────────────────┤ │
│  │  Resources (5) │ Prompts (4)                │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │          ToolContext (unified DI)           │ │
│  │  server │ bridge │ deviceManager            │ │
│  │  logger │ security │ config                 │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │           Middleware Layer                  │ │
│  │  OutputProcessor │ SecurityMiddleware       │ │
│  │  InputSanitizer │ Logger (stderr-safe)      │ │
│  └───────────────────┬─────────────────────────┘ │
│                      │                           │
│  ┌───────────────────▼─────────────────────────┐ │
│  │         Bridge Layer (auto-detect)          │ │
│  │                                             │ │
│  │  ┌─────────────┐    ┌────────────────────┐  │ │
│  │  │  ADB Bridge  │ OR │  Local Bridge      │ │ │
│  │  │  (PC mode)   │    │  (on-device mode)  │ │ │
│  │  │  via adb.exe │    │  via sh/su direct  │ │ │
│  │  └──────┬───────┘    └────────┬───────────┘ │ │
│  │         │                     │             │ │
│  │  Retry │ Timeout │ Cache │ Serial routing   │ │
│  └─────────┼─────────────────────┼─────────────┘ │
└────────────┼─────────────────────┼───────────────┘
             │                     │
     ┌───────▼───────┐    ┌───────▼───────┐
     │  ADB Binary   │    │   sh / su     │
     │  (USB/WiFi)   │    │   (local)     │
     └───────┬───────┘    └───────┬───────┘
             │                    │
       ┌─────▼────────────────────▼─────┐
       │          Android Device        │
       └────────────────────────────────┘

Dual-Mode Architecture

DeepADB operates in two modes, auto-detected at startup:

ADB Mode (default) — PC-side bridge

AI Agent (PC) ←→ MCP ←→ DeepADB (PC) ←→ ADB (USB) ←→ Android Device

Standard mode: DeepADB runs on a PC/Mac/Linux host and communicates with the device over USB via ADB. All 204 tools work through the ADB bridge with automatic retry on transient failures.

On-Device Mode — direct local execution

AI Agent (Termux) ←→ MCP (stdio/HTTP) ←→ DeepADB (Termux) ←→ sh/su (local)

When DeepADB runs directly on the Android device (e.g., inside Termux), it auto-detects the environment and switches to LocalBridge. Commands execute directly via sh/su — no ADB server, no USB, no serialization overhead. All 204 tools work identically, with significantly lower latency.

Validated on hardware (Pixel 6a, Android 16, Termux + Magisk + QEMU 10.2.1) across a four-cell test matrix — host (ADB) and on-device (LocalBridge), each with and without a device PIN — with 0 failures in every cell. The full suite is 577 tests in the host/ADB configuration and 613 on-device; the difference is the QEMU virtualization and Alpine VM-boot suites, which run only on-device:

• ADB mode, no PIN: 556 passed / 0 failed / 21 skipped (577 total). Skips: 5 QEMU (on-device only), 7 gracefulKill unit tests (require POSIX signals, skipped on the Windows host), 3 tcpdump sanitization (tcpdump is root-only and unreachable over a non-root ADB shell), 2 host-shell round-trips (require a POSIX /bin/sh), 4 screen-state (require DATESTPIN).
• ADB mode, with PIN: 560 passed / 0 failed / 17 skipped (577 total). The 4 screen-state tests unlock and run.
• On-device mode, no PIN: 606 passed / 0 failed / 7 skipped (613 total). All QEMU tests run, including Alpine Linux VM boot with KVM acceleration, big.LITTLE CPU topology detection, guest ADB connectivity error handling, and clean VM shutdown; the tcpdump and gracefulKill suites also run here (root + POSIX). Skips: 3 QEMU setup steps that no-op when the Alpine kernel/initrd/disk are already cached, 4 screen-state (require PIN).
• On-device mode, with PIN: 610 passed / 0 failed / 3 skipped (613 total). Every test enabled by the environment runs; the 3 skips are the cached-VM setup steps.

Privilege escalation: In ADB mode, all shell commands run as uid=2000 (the shell user) which has system-level permissions. In Termux, commands run as a regular app user. LocalBridge automatically elevates privileged commands through su when root (Magisk) is available:

• Command allowlist: 16 system commands (settings, dumpsys, am, input, screencap, screenrecord, uiautomator, app_process, getenforce, setenforce, cmd, pm, wm, svc, ip, ifconfig) are routed through su -c to match ADB-mode behavior.
• Path-based elevation: Commands referencing /sdcard, /storage, or /system/ paths are elevated to bypass Android scoped storage restrictions.
• Root detection: Cached after a single su -c id probe at first use. Graceful degradation when root is unavailable.
• The elevation allowlist is frozen (ReadonlySet + Object.freeze) — not configurable via environment variables or runtime API.

Auto-detection: Checks for /system/build.prop (present on all Android devices, never on hosts). Override with DA_LOCAL=true or DA_LOCAL=false.

On-device setup (Termux):

pkg install nodejs-lts git
git clone  && cd deepadb
npm install && npm run build
npm start                              # stdio — for local AI agents (Claude Code, OpenCode)
DA_HTTP_PORT=3000 npm start            # HTTP/SSE — for remote AI access over WiFi

Quick Start

npm install
npm run build
npm run inspector   # Test with MCP Inspector
npm start           # Run directly (stdio mode)

# HTTP/SSE mode for browser-based clients
DA_HTTP_PORT=3000 npm start

# WebSocket mode (requires: npm install ws)
DA_WS_PORT=3001 npm start

# GraphQL API (requires: npm install graphql) — runs alongside any transport
DA_GRAPHQL_PORT=4000 npm start

Claude Code Configuration

{
  "mcpServers": {
    "deepadb": {
      "command": "node",
      "args": ["/path/to/DeepADB/build/index.js"]
    }
  }
}

Available Tools (204)

Health (1 tool)

• adb_health_check — Comprehensive toolchain validation: ADB binary, server, device connection, authorization, root access, and storage writability

Device (3 tools)

• adb_devices — List all connected devices with state, model, and product info
• adb_device_info — Detailed device properties (model, OS, SDK, build, security patch, ABI)
• adb_getprop — Read a specific system property or dump all properties

Shell (2 tools)

• adb_shell — Execute arbitrary shell commands with configurable timeout (security-checked)
• adb_root_shell — Execute commands as root via su (requires rooted device, security-checked)

Packages (12 tools)

• adb_install — Install APK with replace/downgrade options
• adb_uninstall — Remove package with optional data retention
• adb_list_packages — List packages filtered by name or type (all/system/third-party)
• adb_package_info — Detailed package info (version, permissions, paths)
• adb_clear_data — Clear all app data and cache
• adb_grant_permission — Grant a runtime permission to a package
• adb_revoke_permission — Revoke a runtime permission from a package (reset permission state for testing denial flows)
• adb_list_permissions — List all declared and granted permissions for a package, filterable by granted/denied
• adb_force_stop — Force-stop an app immediately
• adb_start_app — Launch an app by package name (resolves launcher activity)
• adb_restart_app — Force-stop then re-launch in one call (configurable delay)
• adb_resolve_intents — Discover registered activities, services, and receivers with intent filters

Files (18 tools)

• adb_push — Push local file to device (hard-blocked kernel paths, fs-type awareness, storage reporting)
• adb_pull — Pull file from device to local filesystem
• adb_ls — List device directory contents (simple or detailed)
• adb_cat — Read text file from device with optional line limit
• adb_file_write — Create or overwrite text files via heredoc (buffer limit warning, fs-aware, post-verify)
• adb_find — Search for files by name/pattern with depth control and result capping
• adb_file_stat — File metadata: size, permissions, timestamps, ownership, SELinux context
• adb_file_checksum — SHA-256/SHA-1/MD5 hash with size-based timeout estimation
• adb_mkdir — Create directories with parent creation (-p), hard-blocked kernel paths
• adb_rm — Delete files/directories with depth-based recursive protection and symlink resolution
• adb_file_move — Move/rename with source depth protection and post-verify
• adb_file_copy — Copy with pre-flight size+space check and post-verify size match
• adb_file_chmod — Change permissions (Zod-validated octal mode, depth-based recursive protection)
• adb_file_touch — Create empty files or update timestamps (explicit timestamp support)
• adb_file_fsinfo — Filesystem report: type, mount, capacity, capabilities, SELinux, limitations
• adb_file_chown — Change ownership (root required, depth-based recursive protection)
• adb_grep — Search file contents with fixed-string default, recursive depth control, result capping
• adb_file_replace — Find/replace text in files (sed-backed, proper escaping, backup option)

Logs — Snapshots (3 tools)

• adb_logcat — Filtered logcat snapshot with tag, priority, grep, and buffer selection
• adb_logcat_clear — Clear all logcat buffers
• adb_logcat_crash — Crash buffer log snapshot

Logs — Persistent Watchers (4 tools)

• adb_logcat_start — Start a background logcat watcher with ring buffer accumulation
• adb_logcat_poll — Retrieve new lines since last poll from a running watcher
• adb_logcat_stop — Stop a watcher session (or all sessions)
• adb_logcat_sessions — List all active watcher sessions with stats

Diagnostics (9 tools)

• adb_dumpsys — Run dumpsys for any service (or list all services)
• adb_telephony — Cell info, signal strength, and network registration (parallel query)
• adb_battery — Battery status, level, temperature, and charging info
• adb_network — WiFi, cellular, and IP connectivity (parallel query)
• adb_top — CPU and memory usage snapshot
• adb_perf_snapshot — Parallel memory, frame stats, and CPU profiling for a package
• adb_bugreport — Full bug report zip capture (device state, logs, system info)
• adb_crash_logs — ANR traces and tombstone crash dumps from /data/anr/ and /data/tombstones/
• adb_heap_dump — Capture heap dump (.hprof) from a running process for memory analysis

UI (10 tools)

• adb_screencap — Take screenshot with filename sanitization, saves locally
• adb_screencap_annotated — Screenshot with UI element bounding boxes and numbered labels composited onto the PNG. Returns annotated image path plus a text legend. Ideal for LLM workflows that reference elements by number
• adb_current_activity — Get focused activity and top window stack
• adb_input — Send tap, swipe, text, or keyevent input
• adb_start_activity — Launch activities by intent or component name
• adb_ui_dump — Dump full UI hierarchy. Supports three output formats: text (default, human-readable), tsv (compact tab-separated for token-efficient automation loops), xml (raw uiautomator XML)
• adb_ui_find — Search UI hierarchy by text, resource-id, or content-description (returns tap coordinates)
• adb_screen_state — Combined screen state in one call: foreground activity, screen dimensions and density, orientation, battery level, and a TSV list of interactive elements. Replaces 3–4 separate tool calls
• adb_screenrecord_start — Start recording the device screen (1-180s, stored on device)
• adb_screenrecord_stop — Stop recording and pull the mp4 video file locally

Device Control (9 tools)

• adb_airplane_mode — Toggle airplane mode with broadcast and verification
• adb_airplane_cycle — Cycle airplane mode on/off to force cellular re-registration
• adb_wifi — Enable or disable WiFi
• adb_mobile_data — Enable or disable mobile data
• adb_location — Set location mode (off/sensors/battery/high)
• adb_screen — Wake, sleep, toggle, lock, or unlock the screen. Lock verifies keyguard state via dumpsys window. Unlock uses wm dismiss-keyguard (works for swipe keyguards); supply pin to perform the full PIN entry sequence: wakes screen, swipes up to reveal keypad, types PIN, confirms, and verifies the keyguard sleep token was released
• adb_settings_get — Read any Android setting from system/secure/global namespace
• adb_settings_put — Write any Android setting with read-back verification
• adb_reboot — Reboot device (normal, recovery, or bootloader mode)

Wireless Debugging (4 tools)

• adb_pair — Pair with device over WiFi using pairing code
• adb_connect — Connect to device over WiFi/TCP
• adb_disconnect — Disconnect wireless device(s)
• adb_tcpip — Switch USB device to TCP/IP mode (auto-detects device IP)

Port Forwarding (8 tools)

• adb_forward — Forward a local port to a device port (host → device)
• adb_reverse — Reverse-forward a device port to the host (device → host)
• adb_forward_list — List all active forward and reverse port mappings
• adb_forward_remove — Remove a port forward or all fo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fullread
• Source: fullread/DeepADB
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.