README.md•4.66 kB
# ADB MCP Server
[](https://smithery.ai/server/@srmorete/adb-mcp)
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
### Installing via Smithery
To install ADB Android Device Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@srmorete/adb-mcp):
```bash
npx -y @smithery/cli install @srmorete/adb-mcp --client claude
```
### Manual 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
### ADB Path Configuration
The server uses default ADB paths. For custom ADB location:
```bash
export ADB_PATH=/path/to/adb
npx adb-mcp
```
### MCP Configuration
Add the ADB MCP server configuration:
```json
{
"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:
```bash
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](LICENSE) file for details.
## Acknowledgments
- Built with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)