# 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/
```