Content
# ADB Model Context Protocol (MCP) Server
A high-performance Model Context Protocol (MCP) server that exposes Android Debug Bridge (ADB) capabilities. This allows AI assistants (such as Claude Desktop or other MCP-compatible clients) to interact with and control Android devices (emulators or physical hardware) directly from the conversation.
## Features
- **Zero Configuration (Auto-Downloader)**: On startup, the server automatically checks if ADB is available. If missing, it will automatically detect the operating system (Windows, macOS, or Linux), download the official Google Platform-Tools, extract it locally, and start using it instantly.
- **Rich Output Inspection**: Captures screenshots directly from the device and delivers them **inline** to the LLM as high-quality PNG content blocks.
- **Complete Suite of 26 Tools**: Full control over shell scripts, file transfers, key input events, application execution, diagnostic information, and device control.
---
## 🚀 Setup & Installation
### Prerequisite
Make sure you have [Node.js (v22+)](https://nodejs.org/) installed.
### 1. Clone & Install Dependencies
Clone the repository and install packages:
```bash
git clone https://github.com/RedZONERROR/AdbMCP.git
cd AdbMCP
npm install
```
---
## ⚙️ Configuration for Claude Desktop
To add the ADB MCP server to Claude Desktop, edit your config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add the server definition inside the `mcpServers` object:
```json
{
"mcpServers": {
"adb-mcp": {
"command": "node",
"args": [
"/absolute/path/to/adb-mcp/index.js"
]
}
}
}
```
Replace `/absolute/path/to/adb-mcp/index.js` with the actual path to the repository on your machine:
- **Windows Example**: `C:/path/to/adb-mcp/index.js` *(Note: Use forward slashes `/` in the configuration file to prevent escaping errors)*.
- **macOS Example**: `/Users/YOUR_USERNAME/GitHub/adb-mcp/index.js`
- **Linux Example**: `/home/YOUR_USERNAME/GitHub/adb-mcp/index.js`
---
## 🛠️ List of Exposed Tools
The server registers 26 distinct tools:
### Device Discovery & Control
- `adb_list_devices`: List all attached devices or emulators with model and status.
- `adb_device_info`: Retrieve detailed hardware specs, battery levels, resolution, and OS properties.
- `adb_reboot`: Reboot the device (normal, bootloader, or recovery mode).
### Shell Execution & App Management
- `adb_shell`: Execute shell commands (e.g. `pm list packages`, `df -h`) on the device.
- `adb_run_script`: Run complex multi-line shell scripts securely by uploading them to the device and running them with standard line-ending compatibility.
- `adb_install`: Install a local `.apk` file from the host machine to the device.
- `adb_uninstall`: Uninstall an application package.
- `adb_list_packages`: List packages installed on the device (can filter by query or third-party only).
- `adb_start_app`: Launch an app using package name (and optional activity).
- `adb_stop_app`: Force-stop an application package.
- `adb_clear_app_data`: Clear the user data and cache of a package (`pm clear`).
- `adb_grant_permission`: Grant or revoke runtime permissions (e.g., `CAMERA`, `WRITE_EXTERNAL_STORAGE`).
### User Interaction & Input Emulator
- `adb_screenshot`: Capture the device screen and return it as an inline image (PNG base64).
- `adb_keyevent`: Send a key event (Home, Back, Power, volume, etc.).
- `adb_input_text`: Type text into the currently active input field.
- `adb_tap`: Tap at specific `(x, y)` coordinates.
- `adb_swipe`: Swipe from `(x1, y1)` to `(x2, y2)` with duration.
- `adb_current_activity`: Retrieve package and class name of the currently focused activity.
### Device File System Management
- `adb_file_push`: Upload a file or directory from the host machine to the device.
- `adb_file_pull`: Download a file or directory from the device to the host machine.
- `adb_device_ls`: List files and folders inside a device folder.
- `adb_device_rm`: Delete a file or directory on the device.
- `adb_device_mv`: Move or rename a file or directory on the device.
- `adb_device_cp`: Copy a file or directory on the device.
- `adb_device_mkdir`: Create a new directory on the device.
### Logs
- `adb_logcat`: Dump recent logs from logcat with optional filters.
---
## 💡 Manual Testing
You can run the server directly via the command line to check for errors or verify ADB resolution:
```bash
npm start
```
*Note: Since it runs on stdio transport, it will wait for JSON-RPC input. To exit, press `Ctrl+C`.*
To run tests with a visual console output, see `test.js`.
