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)

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