Skip to main content
Glama
Sign In
deenesjakoruzh
ADB MCP Server

ADB MCP Server

by srmorete
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

ARCHIVED -- Use mobile-device-mcp

Quite surprised that this repo reached 50 stars (!) the ecosystem is quite generous sometimes, thank you for starring it!

I've been working on something that is faster, more scalable and also works with iOS, take a look at mobile-device-mcp.

And leave some ⭐ too :)

ADB MCP Server

An MCP (Model Context Protocol) server for interacting with Android devices through ADB. This TypeScript-based tool provides a bridge between AI models and Android device functionality.

Related MCP server: mcp-android-emulator

Features

  • 📱 Device Management - List and interact with connected Android devices

  • 📦 App Installation - Deploy APK files to connected devices

  • 📋 Logging - Access device logs through logcat

  • 🔄 File Transfer - Push and pull files between device and host

  • 📸 UI Interaction - Capture screenshots and analyze UI hierarchy

  • 🔧 Shell Command Execution - Run custom commands on the device

Prerequisites

  • Node.js (v16 or higher recommended, tested with Node.js v16, v18, and v20)

  • ADB (Android Debug Bridge) installed and in your PATH

  • An Android device or emulator connected via USB or network with USB debugging enabled

  • Permission to access the device (accepted debugging authorization on device)

Installation

Installing via Smithery

To install ADB Android Device Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @srmorete/adb-mcp --client claude

Manual Installation

# Clone the repository
git clone https://github.com/srmorete/adb-mcp.git
cd adb-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run the server
npx adb-mcp

Configuration

ADB Path Configuration

The server uses default ADB paths. For custom ADB location:

export ADB_PATH=/path/to/adb
npx adb-mcp

MCP Configuration

Add the ADB MCP server configuration:

{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": [
        "adb-mcp"
      ]
    }
  }
}

Usage

Starting the Server

IMPORTANT: The server must be running before using any ADB tools.

Start the server using:

npx adb-mcp

You should see:

[INFO] ADB MCP Server connected and ready

Keep this terminal window open while using the ADB tools.

Available Tools

All tools are available with the following naming convention:

📱 Device Management

  • adb_devices - List connected devices

  • adb_shell - Execute shell commands on a device

📦 App Management

  • adb_install - Install an APK file using a local file path

  • adb_package_manager - Execute Package Manager (pm) commands - list packages, grant/revoke permissions, manage apps

  • adb_activity_manager - Execute Activity Manager (am) commands - start activities, broadcast intents, control app behavior

📋 Logging

  • adb_logcat - View device logs with optional filtering

🔄 File Transfer

  • adb_pull - Pull files from a device

  • adb_push - Push files to a device

🔍 UI Interaction

  • dump_image - Take a screenshot of the current screen

  • inspect_ui - Get UI hierarchy in XML format (most useful for AI interaction)

Troubleshooting

If tools aren't working:

  • Server Issues:

    • Ensure the server is running (npx adb-mcp)

    • Check server output for error messages

    • Try detailed logs: LOG_LEVEL=3 npx adb-mcp

    • Kill hanging processes:

      • ps aux | grep "adb-mcp" | grep -v grep

      • then kill -9 [PID]

  • Device Connection:

    • Verify connection with adb_devices

    • If "unauthorized", accept debugging authorization on device

    • Check USB/network connections

    • Try restarting ADB: adb kill-server && adb start-server

  • ADB Issues:

    • Verify ADB installation: adb version

  • Device Setup:

    • Use an emulator (it was built using one), for real devices maybe try this:

      • Ensure USB debugging is enabled

      • For newer Android versions, enable "USB debugging (Security settings)"

      • Try different USB port or cable

      • or let me know in an issue

Compatibility

  • Android 8.0 and higher

  • MCP clients including Claude in Cursor IDE

  • Was built on macOS but should run on any POSIX compatible (Linux etc).

  • Did not try on Windows but maybe it works.

Contributing

  • Contributions are welcome! Submit a Pull Request.

  • For major changes, open an issue to discuss first.

  • You can, of course, also fork it

  • Note: this project was vibe-coded so if you spot some weird stuff... well now you know 🙂

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Available Tools

10 tools
adb_activity_managerA

Executes Activity Manager (am) commands on a connected Android device. Supports starting activities, broadcasting intents, force-stopping packages, and other 'am' subcommands. Specify the subcommand (e.g. 'start', 'broadcast', 'force-stop') and arguments as you would in adb shell am. Example: amCommand='start', amArgs='-a android.intent.action.VIEW -d http://www.example.com'

Inputs: amCommand (required), amArgs, device.

adb_devicesA

Lists all connected Android devices and emulators with their status and details. Use this tool to identify available devices for interaction, verify device connections, and obtain device identifiers needed for other ADB commands. Returns a table of device IDs with connection states (device, offline, unauthorized, etc.). Useful before running any device-specific commands to ensure the target device is connected.

Inputs: random_string.

adb_installA

Installs an Android application (APK) on a connected device or emulator. Use this for deploying applications, testing new builds, or updating existing apps. Provide the local path to the APK file for installation. Automatically handles the installation process, including replacing existing versions. Specify a device ID when working with multiple connected devices.

Inputs: apkPath (required), device.

adb_logcatA

Retrieves Android system and application logs from a connected device. Ideal for debugging app behavior, monitoring system events, and identifying errors. Supports filtering by log tags or expressions to narrow down relevant information. Results can be limited to a specific number of lines, making it useful for both brief checks and detailed analysis. Use when troubleshooting crashes, unexpected behavior, or performance issues.

Inputs: filter, device, lines.

adb_package_managerB

Executes Package Manager (pm) commands on a connected Android device. Supports listing packages, installing/uninstalling apps, managing permissions, and other 'pm' subcommands. Common commands include: 'list packages', 'install', 'uninstall', 'grant', 'revoke', 'clear', 'enable', 'disable'. Example: pmCommand='list', pmArgs='packages -3' (lists third-party packages) or pmCommand='grant', pmArgs='com.example.app android.permission.CAMERA'

Inputs: pmCommand (required), pmArgs, device.

adb_pullA

Transfers a file from a connected Android device to the server. Use this to retrieve app data files, logs, configurations, or any accessible file from the device. The file content can be returned as base64-encoded data or as a success message. Requires the full path to the file on the device. Useful for data extraction, log collection, and backing up device files.

Inputs: remotePath (required), device, asBase64.

adb_pushA

Transfers a file from the server to a connected Android device. Useful for uploading test data, configuration files, media content, or any file needed on the device. The file must be provided as base64-encoded content. Requires specifying the full destination path on the device where the file should be placed. Use this when setting up test environments, restoring backups, or modifying device files.

Inputs: fileBase64 (required), remotePath (required), device.

adb_shellA

Executes a shell command on a connected Android device or emulator. Use this for running Android system commands, managing files and permissions, controlling device settings, or interacting with Android components. Supports all standard shell commands available on Android (ls, pm, am, settings, etc.). Specify a device ID to target a specific device when multiple devices are connected.

Inputs: command (required), device.

dump_imageA

Captures the current screen of a connected Android device. FOR HUMAN VIEWING ONLY: This tool provides a visual image that cannot be easily processed programmatically. The screenshot shows exactly what appears on the device screen at the moment of capture. The default behavior returns a success message. Use asBase64=true to get the image as base64-encoded data. No additional parameters required beyond an optional device ID. Use when you need to visually verify UI elements for human inspection only. NOTE: For programmatic analysis or to identify UI elements, use inspect-ui instead.

Inputs: device, asBase64.

inspect_uiA

Captures the complete UI hierarchy of the current screen as an XML document. This provides structured XML data that can be parsed to identify UI elements and their properties. Essential for UI automation, determining current app state, and identifying interactive elements. Returns the UI structure including all elements, their IDs, text values, bounds, and clickable states. This is significantly more useful than screenshots for AI processing and automation tasks.

Inputs: device, outputPath, asBase64.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct ADB functionality, from device listing and file transfer to UI inspection and package management, with no overlapping purposes.

    Naming Consistency4/5

    Most tools follow 'adb_' prefix, but 'dump_image' and 'inspect_ui' lack the prefix, creating a minor inconsistency in an otherwise predictable pattern.

    Tool Count5/5

    With 10 tools, the collection covers essential ADB operations without being excessive or insufficient, well-scoped for typical device management tasks.

    Completeness4/5

    The set covers major ADB workflows including device management, app installation, logging, file transfer, and UI inspection, though a dedicated uninstall tool is absent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches