@samsadch/adb-mcp

v0.0.3

Published

8 days ago

Model Context Protocol (MCP) server for Android ADB: inspect databases, capture screenshots, manage apps, edit SharedPreferences, and control devices with AI agents in Antigravity, Claude, Cursor, and Windsurf.

@samsadch/adb-mcp 🤖📱

Model Context Protocol (MCP) server that empowers AI coding agents (Google Antigravity, Claude Code, Cursor, Windsurf, Claude Desktop) to directly see, control, inspect, and debug connected Android devices and emulators over ADB.

Part of ADB Controller by Samsad. Powered by the shared capability layer @samsadch/adb-core.

⚡ Highlights

100% Offline & Private: Direct local ADB bridge communication. Zero telemetry, zero cloud relay.
Sticky Target Pinning: Call set_target once; all subsequent tools infer the active device and package.
Multimodal Vision: Real-time PNG screen capture for multimodal visual reasoning.
Structured UI Automator Inspection: Complete UI hierarchy extraction with bounding box calculations and clickable state resolution.
Smart Touch & Gestures: Tap by text, ID, or coordinates; swipe with auto-calculated screen geometry; dispatch hardware keycodes.
App Lifecycle & Runtime Permissions: Install APKs, clear caches, restart apps, grant/revoke permissions dynamically.
Deep SQLite & SharedPreferences Inspection: Query SQLite databases, browse tables, create tables, truncate, delete rows, and edit SharedPreferences XML with strict data typing.
Non-blocking Logcat & Memory Diagnostics: Real-time log capture with PID/tag/severity filters and dumpsys meminfo process allocation breakdowns.
Hardware & Power Simulator: Simulated battery levels, discharge states, Doze idle states, UI theme toggles, and broadcast intent injection.
File Transfers & Shell Execution: Push/pull files and directories, and execute ad-hoc device shell commands.

🚀 Quick Setup & Usage

1. Claude Code

claude mcp add adb -- npx -y @samsadch/adb-mcp

2. Google Antigravity / Cursor / Windsurf / Claude Desktop

Add to your mcp_config.json or MCP settings:

{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": ["-y", "@samsadch/adb-mcp"]
    }
  }
}

3. Android Studio (HTTP transport)

Android Studio's Gemini integration connects only to a streamable HTTP endpoint — it cannot spawn a stdio process. Start the server in HTTP mode:

npx -y @samsadch/adb-mcp --http

Then go to Settings → Tools → AI → MCP Servers, enable MCP servers, and add:

{
  "mcpServers": {
    "adb": {
      "httpUrl": "http://127.0.0.1:3579/mcp"
    }
  }
}

Type /mcp in the Gemini chat to confirm the tools loaded. GET /healthz reports status and the live session count if you need to debug the connection.

The server binds to 127.0.0.1 only. These tools run arbitrary shell commands on the attached device and can read app databases, so exposing the port to a network would hand that control to anyone who can reach it. Binding elsewhere requires an explicit --allow-external, and the server prints a warning when you do.

Options: --port <n> (default 3579), --host <addr> (default 127.0.0.1), --allow-external, --help. The equivalents ADB_MCP_TRANSPORT=http, ADB_MCP_PORT and ADB_MCP_HOST work for clients that only let you set environment variables.

Each HTTP session gets its own server instance, so the sticky target set by one client never leaks into another.

4. Run Locally from Source

git clone https://github.com/samsadch/SamsadADBController.git
cd SamsadADBController
npm install
npm run build --workspace=@samsadch/adb-mcp
node packages/adb-mcp/out/index.js          # stdio
node packages/adb-mcp/out/index.js --http   # streamable HTTP

🛠️ Complete MCP Tool Catalog (51 Tools)

1. Device Discovery & Sticky Target (3 Tools)

2. Eyes & Hands: UI Vision & Precision Automation (8 Tools)

| Tool | Description | | :--- | :--- | | take_screenshot | Captures a live screenshot as a multimodal PNG image. | | dump_view_hierarchy | Dumps structured on-screen UI hierarchy JSON with bounding boxes, center coordinates, IDs, and click states. | | tap_element | Finds an on-screen UI element by visible text, resource-id, or content-desc and taps its center. | | tap_coordinates | Performs a touch event at specific (x, y) pixel coordinates. | | input_text | Types text into the active input field with automated character and space escaping. | | press_key | Dispatches hardware/navigation keys (BACK, HOME, RECENTS, ENTER, LOCK, VOLUP, VOLDOWN, TAB, DELETE, etc.) or keycodes. | | swipe_screen | Swipes by direction ("up", "down", "left", "right") or explicit start/end coordinates. | | open_deep_link | Dispatches Android VIEW Intents with URI schemes and App Links. |

3. App Lifecycle & Permission Management (10 Tools)

4. SQLite Database Inspection & Modification (10 Tools)

5. SharedPreferences Management (6 Tools)

6. Logs, Performance & System Diagnostics (3 Tools)

7. Device Controls & Power Simulator (8 Tools)

| Tool | Description | | :--- | :--- | | set_battery_level | Simulates a specific battery level percentage (0-100) and unplugs device power. | | unplug_battery | Simulates disconnecting device from AC/USB charger (sets battery state to discharging). | | reset_battery | Restores battery status to actual physical hardware state. | | force_doze_mode | Forces device into deep Doze mode (idle state) for testing background tasks and battery optimizations. | | exit_doze_mode | Wakes device from Doze mode (unforce). | | toggle_dark_mode | Switches system UI theme between Dark Mode and Light Mode, or sets an explicit mode (light, dark, toggle). | | toggle_animations | Enables or disables system animations (window, transition, and animator scales) or toggles between 1.0x and 0.0x. | | send_broadcast | Sends custom broadcast intent with action, package, component, and typed extras dictionary. |

8. File Transfers & Safe Ad-hoc Shell (3 Tools)

🔧 Environment Configuration

All environment variables are optional. The server automatically discovers SDK paths: