Content
# Android ADB MCP Server
This is an Android ADB server based on the MCP (Message Communication Protocol) that allows remote control of Android devices connected to a computer via Claude for Desktop or other MCP clients.
## Features
- **Device Management**: List connected Android devices
- **Screen Operations**: Screenshot, tap, swipe (up, down, left, right)
- **Input Operations**: Text input, key simulation
- **Application Management**: Install/uninstall applications, launch applications
- **System Operations**: Retrieve device information such as screen resolution
- **Network Tools**: Get network status, port scanning, WIFI management
- **File Tools**: File upload/download, file management
- **Advanced Tools**: UI testing, performance analysis, screen recording, log collection, enhanced application launch
## Prerequisites
1. Python 3.10 or higher
2. ADB installed and added to the system path
3. Android device with USB debugging enabled and connected to the computer
## Installation
```bash
# Clone this repository
git clone https://github.com/wolfcoming/adb_mcp_server.git
cd adb_mcp_server
# Install dependencies
pip install -r requirements.txt
# Ensure the ADB server is started
adb start-server
```
## Usage
### Configuration in Claude for Desktop
1. Install [Claude for Desktop](https://claude.ai/desktop)
2. Configure the MCP server:
- Locate the Claude for Desktop configuration file, usually found at `~/Library/Application Support/Claude/claude_desktop_config.json`
- Add the following configuration:
```json
{
"mcpServers": {
"android_adb": {
"command": "python",
"args": [
"-m",
"src.adb_server"
],
"cwd": "/path/to/adb_mcp_server"
}
}
}
```
3. Restart Claude for Desktop
### Configuration in Cursor
1. Locate the Cursor configuration file, usually found at `~/.cursor/mcp.json`
2. Add the following configuration:
```json
{
"mcpServers": {
"android_adb": {
"command": "python",
"args": [
"-m",
"src.adb_server"
],
"cwd": "/path/to/adb_mcp_server"
}
}
}
```
3. Restart Cursor
## Supported Tools
### Device Management
- `list_devices`: List all connected Android devices
### Screen Operations
- `take_screenshot`: Capture the device screen
- `tap_screen`: Tap on a specified location on the screen
- `swipe_up`: Swipe up
- `swipe_down`: Swipe down
- `swipe_left`: Swipe left
- `swipe_right`: Swipe right
### Input Operations
- `input_text`: Input text
- `press_key`: Press a specified key
- `press_back`: Press the back key
- `press_home`: Press the home key
### Application Management
- `start_app`: Launch an application
- `install_apk`: Install an APK
- `uninstall_app`: Uninstall an application
### System Operations
- `get_screen_resolution`: Get screen resolution
### Network Tools
- `get_ip_address`: Get device IP address
- `ping`: Test network connection
- `scan_ports`: Scan specified ports
- `get_wifi_status`: Get WIFI status
- `connect_wifi`: Connect to a WIFI network
### File Tools
- `list_files`: List files in a directory
- `upload_file`: Upload a file to the device
- `download_file`: Download a file from the device
- `create_file`: Create a file
- `delete_file`: Delete a file
### Advanced Tools
- `dump_ui_hierarchy`: Get UI hierarchy
- `run_ui_test`: Execute UI test steps
- `check_element_exists`: Check if a UI element exists
- `tap_element_by_text`: Tap on a UI element containing specified text
- `collect_device_logs`: Collect device logs
- `analyze_performance`: Analyze application performance
- `take_screen_recording`: Record a video of the device screen
- `enhanced_start_app`: Enhanced application launch functionality that can bypass permission restrictions
## Example Usage
In Claude for Desktop, you can use it like this:
```
# Device related
"I want to see the connected Android devices"
"Please take a screenshot of my Android device"
# Application operations
"Please install this APK file: /path/to/app.apk"
"Please launch the settings application (com.android.settings)"
"Please use the enhanced launch feature to open the China News app, even if there are permission issues"
# Input and interaction
"Please tap on the screen coordinates (500, 500)"
"Please swipe up from the bottom of the screen"
"Please tap the button containing the text 'Settings'"
# File operations
"Please list the files in the /sdcard/ directory on the device"
"Please download the /sdcard/DCIM/pic.jpg from the device to my computer"
# Network operations
"Please check the WIFI status of the device"
"Please connect to the network named 'MyWifi'"
# Advanced features
"Please analyze the performance of the 'com.example.app' application for 30 seconds"
"Please record a 10-second video of the screen"
"Please collect the recent device logs"
```
## Tips
- If you encounter issues, ensure the ADB server is started (`adb start-server`)
- Make sure the Android device has authorized your computer for USB debugging
- Some operations may require root permissions
- If you encounter "Permission Denial" issues, please use the `enhanced_start_app` advanced tool
## Contribution
Contributions and issues are welcome! Feel free to submit Pull Requests or create Issues.
## License
MIT © [wolfcoming](https://github.com/wolfcoming)
