Deepadb

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:

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.

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 th