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

``bash


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

$3

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

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

$3

Add the ADB MCP server configuration:
`json
{
"mcpServers": {
"adb": {
"command": "npx",
"args": [
"adb-mcp"
]
}
}
}
`

Usage

$3

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

Start the server using:

`bash
npx adb-mcp
`

You should see:
`
[INFO] ADB MCP Server connected and ready
`

Keep this terminal window open while using the ADB tools.

$3

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)