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.

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

# 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

📋 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

• Built with Model Context Protocol (MCP)