mcp-adb/README.md

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, device_id?)

Send input events:

• tap: Tap at coordinates (x, y)
• swipe: Swipe from (x, y) to (x2, y2)
• key: Send key event (key_code)
• text: Type text

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?)

Execute shell command on device.

Usage

Using uvx (Recommended)

# Run directly with uvx
uvx android-mcp-server

# Or from PyPI once published
uvx android-mcp-server

Local Development

# Install dependencies
uv sync

# Run the server
uv run android-mcp-server

Docker Development

# 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:

{
  "mcpServers": {
    "android-adb": {
      "command": "uvx",
      "args": ["android-mcp-server"]
    }
  }
}

Local Development

{
  "mcpServers": {
    "android-adb": {
      "command": "uv",
      "args": ["run", "android-mcp-server"],
      "cwd": "/path/to/android-mcp-server"
    }
  }
}

Docker

{
  "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

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