Ryan Malloy
da7cde1fc3
- Added comprehensive examples for tap, swipe, key, and text input - Made it clear that shell command is the most reliable way for coordinates - Updated README to highlight adb_shell_command as recommended for tap/swipe - Added practical examples like scrolling and common shell commands - Improved parameter descriptions with real usage examples This provides a clear workaround for the MCP coordinate validation issues while making the tool much more usable for Android automation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
# Android MCP Server
|
|
|
|
A Model Context Protocol (MCP) server for Android device automation via ADB. This server provides tools for interacting with Android devices through ADB commands in a structured, type-safe way.
|
|
|
|
## Features
|
|
|
|
- **Device Management**: List and interact with connected Android devices
|
|
- **Screenshots**: Capture and retrieve device screenshots
|
|
- **Input Simulation**: Send taps, swipes, key events, and text input
|
|
- **App Control**: Launch apps by package name or open URLs
|
|
- **Package Management**: List installed packages
|
|
- **Shell Commands**: Execute arbitrary shell commands on device
|
|
|
|
## Tools Available
|
|
|
|
### `adb_devices()`
|
|
List all connected Android devices with their IDs and status.
|
|
|
|
### `adb_screenshot(device_id?, local_filename?)`
|
|
Take a screenshot and save it locally.
|
|
|
|
### `adb_input(action_type, ...parameters, device_id?)`
|
|
Send input events (key and text actions work reliably):
|
|
- `key`: Send key event - `adb_input(action_type="key", key_code="KEYCODE_BACK")`
|
|
- `text`: Type text - `adb_input(action_type="text", text="hello")`
|
|
|
|
### `adb_launch_app(package_name, device_id?)`
|
|
Launch an app by package name.
|
|
|
|
### `adb_launch_url(url, device_id?)`
|
|
Open URL in default browser.
|
|
|
|
### `adb_list_packages(device_id?, filter_text?)`
|
|
List installed packages, optionally filtered.
|
|
|
|
### `adb_shell_command(command, device_id?)` - **RECOMMENDED for tap/swipe**
|
|
Execute shell commands including reliable input simulation:
|
|
- **Tap**: `adb_shell_command(command="input tap 400 600")`
|
|
- **Swipe**: `adb_shell_command(command="input swipe 100 200 300 400")`
|
|
- **Scroll down**: `adb_shell_command(command="input swipe 500 800 500 300")`
|
|
- **Key press**: `adb_shell_command(command="input keyevent KEYCODE_BACK")`
|
|
- **Type text**: `adb_shell_command(command="input text \"hello world\"")`
|
|
- Other commands: `ls /sdcard`, `pm list packages | grep chrome`
|
|
|
|
## Usage
|
|
|
|
### Using uvx (Recommended)
|
|
```bash
|
|
# Run directly with uvx
|
|
uvx android-mcp-server
|
|
|
|
# Or from PyPI once published
|
|
uvx android-mcp-server
|
|
```
|
|
|
|
### Local Development
|
|
```bash
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Run the server
|
|
uv run android-mcp-server
|
|
```
|
|
|
|
### Docker Development
|
|
```bash
|
|
# Build and run with Docker Compose
|
|
docker-compose up --build
|
|
|
|
# Or build manually
|
|
docker build -t android-mcp-server .
|
|
docker run --privileged -v /dev/bus/usb:/dev/bus/usb android-mcp-server
|
|
```
|
|
|
|
## MCP Client Configuration
|
|
|
|
### Using uvx (Recommended)
|
|
Add to your MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "uvx",
|
|
"args": ["android-mcp-server"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Local Development
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "uv",
|
|
"args": ["run", "android-mcp-server"],
|
|
"cwd": "/path/to/android-mcp-server"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Docker
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"android-adb": {
|
|
"command": "docker",
|
|
"args": ["run", "--privileged", "-v", "/dev/bus/usb:/dev/bus/usb", "android-mcp-server"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+
|
|
- ADB (Android Debug Bridge)
|
|
- USB access to Android devices
|
|
- Device with USB debugging enabled
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dev dependencies
|
|
uv sync --group dev
|
|
|
|
# Format code
|
|
uv run black src/
|
|
|
|
# Lint
|
|
uv run ruff check src/
|
|
|
|
# Type check
|
|
uv run mypy src/
|
|
``` |