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)