DeepADB MCP server

DeepADB

MCP (Model Context Protocol) server for AI agents that need to inspect, control, test, and diagnose Android devices through ADB—or directly on-device through Termux.

209 tools, 5 resources, and 4 prompts across 49 modules—from UI automation and application management to logs, network capture, baseband, firmware, security, and hardware diagnostics.

Get started

DeepADB runs as a local MCP server. It uses ADB on a host computer and automatically switches to direct execution when running on Android (detected through /system/build.prop).

git clone https://github.com/fullread/DeepADB.git
cd DeepADB
npm ci
npm run build
npm start

Add build/index.js to your MCP client configuration, then begin with these workflows:

Goal	Start with
Confirm the toolchain and connected device	adb_health_check, then adb_devices
Inspect the current Android UI	adb_screen_state, then adb_ui_dump
Diagnose a device or app	adb_device_info, adb_logcat, and adb_dumpsys

For a guided local connection, see MCP Client Configuration. Read SECURITY.md before exposing HTTP, WebSocket, or GraphQL transports beyond loopback.

Using llama.cpp or another local model? See Local LLM clients for direct stdio, authenticated browser HTTP, and small tool profiles. WebSocket is not required.

Architecture

┌──────────────────────────────────────────────────┐
│                   MCP Client                     │
│             (Any MCP-capable client)             │
└──────────────────────┬───────────────────────────┘
                       │ stdio (JSON-RPC), HTTP (/mcp or /sse), or WebSocket
┌──────────────────────▼───────────────────────────┐
│               DeepADB Server                     │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           Tool Modules (49)                 │ │
│  │  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         │ │
│  │  app-network │ database-inspector           │ │
│  │  runtime-audit │ wear                       │ │
│  ├─────────────────────────────────────────────┤ │
│  │  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. The complete 209-tool surface is registered through the ADB bridge with automatic retry on transient failures; environment-specific tools report their capability requirements when a host cannot run them.

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. The same 209-tool MCP surface is registered, with capability-aware guidance when an optional on-device binary such as sqlite3 is unavailable.

Current test profiles: npm test retains strict rooted Pixel 6a / Android 16 coverage. npm run test:emulator uses a disposable fixture app for portable lifecycle/UI tests and verifies sensor readings against Android's actual inventory. Pixel-only hardware checks have explicit skips in the emulator profile; unexpected failures still fail its optional CI lane. See test setup and profile boundaries. The release baselines below describe the published artifacts. See the Unreleased changelog for subsequent changes and validation.

1.1.6 device validation (November 1, 2026): the released build's full on-device run passed 836 checks, 0 failed, 3 skipped (839 total) across all 24 suites on the rooted Pixel 6a / Android 16, using Termux Node 24.22.1 and SQLite 3.54.1. The three skips reuse the cached Alpine kernel, initrd and disk; the actual VM boot and shutdown checks passed. Coverage includes the 28 runtime-audit regressions, device SQLite, live Shannon AT/OK, client/plugin compatibility, POSIX security cases and PIN-based UI recovery. The production installation passed eight strict checks before and after promotion, plus eight real Chromium checks and six authenticated WebSocket/GraphQL checks. Following the final documentation audit and verified redeployment, 1.1.6 is the only DeepADB installation retained on the validation Pixel; older installations and rollback copies were removed at the operator's request. Real phone-to-watch validation remains deferred.

The earlier 1.1.6 host/ADB baseline on Windows/Node 24.22.2 passed 783 checks, 0 failed, 18 expected skips (801 total). After the oversized-header test was split into a portable regression, Node 22.23.4 device-free coverage passed 351 checks, 0 failed, 17 expected skips (368 total). Host skips cover device-only or POSIX behavior, unavailable tcpdump and Windows file-symlink privileges; they are distinct from the on-device results above.

v1.1.5 final audit-fix verification (Windows host): the ten device-free suites passed 295 checks, zero failures, and 17 expected skips (312 total) under Node 22.23.4 with coverage. The new hardening suite separately passed 41 checks on Node 24.22.2, with one Windows file-symlink capability skip; 16 other skips in the full CI set require hardware. Eight real-browser CORS/reload checks passed. The Pixel passed eight disposable POSIX path/link/race checks and five focused hardware smoke checks; the latest snapshot code also completed a real schema read through the isolated worker. These initial checks preceded the separate on-device release validation described below.

Final hardening hardware regression (October 31, 2026): all 22 host/ADB suites passed on the Pixel 6a / Android 16 using Node 24.22.2: 728 passed, 0 failed, 18 expected skips (746 total). This includes 41 audit-hardening, 33 local-LLM, 36 SDK/client/plugin compatibility, 93 security and 46 UI checks, plus live SQLite and Shannon validation. The skips are five on-device-only QEMU checks, twelve Windows/POSIX/tcpdump checks and one Windows file-symlink capability case. That last case is additionally covered by the disposable Pixel POSIX probes above. The suite exited successfully, left no ADB forwards, and made no repository file changes. This validates the host build; on-device LocalBridge execution is verified separately during release preparation.

1.1.5 release validation: the production-only package initializes with 209 tools, five resources/templates and four prompts. The staged Pixel build, using Termux Node 24.22.1 and SQLite 3.54.1, passed real SQLite schema/query reads, write rejection, runtime/health checks and a live Shannon handshake. Eight real-browser checks also passed against that on-device process, including authenticated SSE/Streamable HTTP, denied Origins and repeated page reloads. Six optional WebSocket/GraphQL checks passed with their production packages installed. The verified build was promoted to the normal installation path; Android auto-detection and all eight strict device checks passed again there. At that release's validation, the 1.1.4 rollback copy also started on the new runtime. The final host hardware rerun passed 728 checks with zero failures and 18 skips; device-free Node 24 coverage passed 295 checks with zero failures and 17 skips. GitHub CI covers Node 22/24/26 builds and regressions, real-browser MCP compatibility, coverage and dependency auditing, with separate CodeQL analysis for application code and GitHub Actions.

Earlier unreleased host hardware validation (October 31, 2026, before the final seven-finding hardening pass): the expanded suite, including SDK migration, browser reconnect, request-ID/cancellation, plugin callback lifetime, and profile regressions, completed on Pixel 6a / Android 16 with 687 passed, 0 failed, and 17 expected skips (704 total). Live llama.cpp checks separately exercised stdio, authenticated browser Streamable HTTP, and legacy SSE with the inspect profile; see LOCAL_LLMS.md for the tested model and browser HTTP reload recovery and its limits. Phone-to-watch Wear validation is deferred.

v1.1.4 host hardware validation: the full Pixel 6a / Android 16 regression completed with 604 passed, 0 failed, and 17 expected environment-specific skips (621 total). This includes live AT/OK validation on /dev/umts_router, a guarded read-only SQLite schema snapshot with cleanup, the unified runtime audit, per-app route context, and the single-device Wear preflight. The skips are the five on-device-only QEMU checks plus twelve Windows-host or unavailable-tcpdump security checks.

v1.1.3 hardware baseline: validated on a 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 v1.1.3 suite contained 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 DA_TEST_PIN).
• 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.
• Screenshot lifecycle: Allocate, capture and remove private device scratch files under the same identity. LocalBridge uses root when available, while the pulled output remains owned by the Termux user. Registered VM targets use ADB on the guest.
• 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 sqlite
git clone https://github.com/fullread/DeepADB.git
cd DeepADB
npm ci
npm run build

Choose the launch mode for your client. For stdio, configure the MCP client to launch node with the absolute path to DeepADB/build/index.js; the client starts the process itself. To run a loopback HTTP listener instead:

DA_HTTP_HOST=127.0.0.1 DA_HTTP_PORT=3000 npm start # /mcp and legacy /sse

This listener is accessible only on the device, not directly over Wi-Fi. For browser clients, configure a bearer token and an exact Origin allowlist; see Local LLM clients. For remote access, follow the token and TLS reverse-proxy or SSH-tunnel guidance in SECURITY.md.

Use a supported Node LTS release; Node 24 is validated for this release. The sqlite package supplies the sqlite3 executable required by on-device database inspection. Production installs that omit development dependencies must install ws and/or graphql separately when those optional transports are enabled. Before replacing an existing device installation, stage the built package, keep a rollback copy, and verify its actual LocalBridge execution with the device's runtime and binaries. Host/ADB tests alone do not validate that deployment.

MCP Client Configuration

Configure a local stdio MCP server with node as the command and the absolute path to build/index.js as its argument. The client starts the server process. For clients that use an mcpServers JSON configuration, the equivalent is:

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

Other clients may use a settings form, TOML, or a different JSON layout; enter the same command and argument using that client's configuration format. Leave DA_HTTP_PORT, DA_WS_PORT, and DA_GRAPHQL_PORT unset for this stdio setup. See Local LLM clients for explicit environment settings and authenticated browser connections.

Available Tools (209)

Start with the capability area that matches your task; the complete reference remains below.

Area	Includes
Inspect & diagnose	Device, packages, files, logs, diagnostics, runtime audit, and SQLite
Control & automate	UI, device control, input automation, and test sessions
Connect & scale	Wireless debugging, port forwarding, per-app routing, Wear preflight, multi-device orchestration, and CI/CD
Analyze Android internals	Network capture, baseband, firmware, SELinux, and sensors
Extend workflows	Plugins, workflow orchestration, device profiles, and result handles

Complete tool reference

Health (1 tool)

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

Runtime Audit (1 tool)

• adb_runtime_audit — Unified read-only readiness audit for transport, Android userspace, root, SELinux, storage, command capabilities, UI/network diagnostics, SQLite, modem nodes, and Wear prerequisites

The audit retains successful checks when an independent probe fails. Its report labels readiness as available, unavailable (a confirmed negative result), or inconclusive (failed, timed out, incomplete, or not safely checked). Audit status: partial and the Probe issues section identify incomplete checks while preserving useful device information and snapshots. A partial report is returned normally; failure to resolve the requested device remains a tool error. complete means the checks completed, not that every capability is available. Modem node visibility does not verify an AT handshake, and Play services presence does not verify phone/watch pairing. Use the dedicated Shannon and Wear tools for those narrower checks.

SQLite readiness follows the inspector's execution mode: host ADB uses the host's Node SQLite backend (Node 22.16+ with node:sqlite enabled), while on-device LocalBridge uses device sqlite3. A phone's SQLite binary cannot make a missing host backend available. Backend availability alone does not verify access to a particular app database.

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

Room & SQLite Inspection (1 tool)

• adb_sqlite_inspect — Package-scoped listing, schema inspection and validated read-only SQL. Prefers run-as, falls back to root, rejects linked directories/files and verifies opened descriptors. Queries a private snapshot (database + WAL ≤64 MiB) with bounded execution and output, then removes it. Host inspection needs Node 22.16+ and runs in an isolated process; on-device inspection uses a trusted sqlite3 binary. Neither backend queries the live app path. Snapshots are not transactional backups; concurrent writes may require retrying with the app stopped.

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