Content
# ADB MCP
Model Context Protocol (MCP) Server, controlling Android devices via ADB for smart screen interaction and automation.
## Features
- 📱 ADB Device Control (screenshot, tap, swipe, input, etc.)
- 🎯 Set-of-Marks (SOM) screenshot annotation technology
- 🤖 Intelligent coordinate analysis and tap (OCR + SOM)
- 🔧 MCP protocol compatibility (stdio mode)
## Requirements
- macOS/Linux/Windows + ADB installed + Android CLI installed
- Android device connected via USB and developer mode enabled
- [uv](https://docs.astral.sh/uv/) package manager
### Python Dependencies
- **mcp**: MCP SDK, providing MCP protocol support
- **easyocr**: OCR text recognition (supporting Chinese and English)
- **torch**: PyTorch, EasyOCR underlying dependency
- **numpy**: numerical computation
- **fastapi / uvicorn / pydantic**: Web framework (reserved for extension)
## Installation
### Install using uv (recommended)
```bash
# 1. Clone or download the project
cd your/path/to/McpAdb
# 2. Install dependencies
uv sync
```
## Start MCP Server
```bash
uv run mcp_server_fast.py
```
The project root directory already contains a `.mcp.json` configuration file. Use `uv run` to start directly:
```json
{
"mcpServers": {
"adb-mcp": {
"command": "uv",
"args": ["run", "mcp_server_fast.py"],
"env": {},
"disabled": false
}
}
}
```
Place `.mcp.json` in the project root directory (or merge it into `~/.claude.json`'s `mcpServers`), and restart Claude Code to automatically load the MCP server.
## Tool List
| Tool | Description |
|------|-------------|
| `list_devices` | List all connected Android devices |
| `take_screenshot` | Capture a screenshot of the current Android screen. Must be called before clicking, finding, or operating on the screen |
| `find_text_on_screen` | Use OCR to find specified text on the screenshot and return coordinates |
| `tap_screen` | Tap the screen at specified coordinates |
| `input_text_to_device` | Input text to the current focus position |
| `swipe_screen` | Perform a swipe operation on the screen |
| `press_android_key` | Press an Android key (e.g., KEYCODE_BACK, KEYCODE_HOME, KEYCODE_ENTER) |
| `go_to_home_screen` | Press the Home key to return to the home screen |
| `go_back_android` | Press the Back key to return to the previous page |
| `launch_android_app` | Launch an Android app |
| `get_device_screen_size` | Get the device screen size |
| `som_screenshot` | Take a screenshot with annotations (Set-of-Marks), labeling all interactive elements on the screen |
| `get_tap_coordinates_by_id` | Parse the physical coordinates corresponding to the digital labels in the SOM screenshot |
| `get_current_activity` | Get the current activity/focus app |
| `get_logcat_logs` | Get Logcat logs (only error level, supporting tail parameter) |
| `execute_shell_command` | Execute a custom ADB shell command |
| `install_android_app` | Install an APK file |
| `uninstall_android_app` | Uninstall an app |
| `push_file_to_device` | Push a file to the device |
| `pull_file_from_device` | Pull a file from the device |
| `wait_seconds` | Wait for a specified number of seconds |
| `cleanup_screenshots` | Clean up temporary screenshot files |
## Project Structure
```
McpAdb/
├── adb_mcp/
│ ├── __init__.py # Package initialization
│ └── adb_controller.py # ADB operation encapsulation (core functions like screenshot, tap, input)
├── mcp_server_fast.py # MCP server main entry (FastMCP stdio mode)
├── pyproject.toml # Project configuration and dependency management
├── .mcp.json # Project-level MCP configuration
└── README.md # Project documentation
```
## Frequently Asked Questions
### Device Not Recognized
```bash
# Check device connection
adb devices
# Restart ADB service
adb kill-server && adb start-server
# Ensure USB debugging is enabled
```
### Permission Issues
```bash
# Grant executable permission to ADB
chmod +x ~/Library/Android/sdk/platform-tools/adb
# Check ADB path
which adb
```
### Screenshot Failure
- Ensure the device is connected via USB
- Ensure developer mode and USB debugging are enabled
- Try re-plugging the USB cable
- Check ADB version compatibility
## License
This project is licensed under the MIT License.
