Repository avatar
Security
v0.1.0
active

android-device-control

io.github.lisn0/android-device-control

Inspect authorized Android devices through ADB.

Documentation

Android Device Control

A local ADB command-line tool and MCP server for inspecting authorized Android devices. Find connected devices, see the foreground app, and read the screen's accessibility tree. The MCP tools are read-only by default, with taps available when explicitly enabled for one device.

PyPI · npm · MCP Registry

Install the CLI · Run the MCP server

Install

Python 3.10 or newer is required. Install adb from Android SDK Platform-Tools and put it on your PATH. In your Python environment, install the CLI.

python -m pip install android-device-control

The CLI uses the Python standard library. If you are working from a clone, you can run the scripts directly with python3 -B phone.py, device_info.py, messages.py, and receipts.py.

Get started

  1. Connect your test device over USB, enable USB debugging, and approve your computer on the device. See Google's ADB setup guide for USB troubleshooting and wireless pairing.

  2. List devices and run a read-only check. Replace DEVICE_SERIAL with the serial shown for your authorized device.

    android-control devices
    android-control-device-info --device DEVICE_SERIAL
    android-control foreground --device DEVICE_SERIAL
    

Open an ordinary test screen on the device to read its accessibility tree.

android-control snapshot --device DEVICE_SERIAL
android-control --help

Use android-control-sms --help for SMS diagnostics and android-control-receipts --help for the local setup receipt ledger.

Run the MCP server

With Node.js, uvx, and adb on your MCP client's PATH, launch the local stdio server from npm:

npx --yes android-device-control

The launcher uses the published PyPI package and forwards options such as --device DEVICE_SERIAL. Call list_devices to check the connection.

Install from PyPI or run with uvx

python -m pip install 'android-device-control[mcp]'

For a client that uses mcpServers JSON, use the installed command on its PATH or set command to the full path to the executable.

{
  "mcpServers": {
    "android-control": {
      "command": "android-control-mcp"
    }
  }
}

With uvx on the client's PATH, use "command": "uvx" and "args": ["--from", "android-device-control[mcp]", "android-control-mcp"].

Run from a checkout

Create a Python environment with the MCP SDK.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-mcp.txt

Replace the example paths with the absolute paths to the environment's Python executable and android_mcp.py.

{
  "mcpServers": {
    "android-control": {
      "command": "/absolute/path/to/android-control/.venv/bin/python",
      "args": ["/absolute/path/to/android-control/android_mcp.py"]
    }
  }
}

Scope tools to a device

The default tools are list_devices (authorized serials and ADB states), foreground (focused package and activity), and snapshot (guarded UI summary). Supply the target serial to foreground and snapshot. To scope every tool to one phone, append "--device", "DEVICE_SERIAL" to args, using the serial shown by android-control devices or python3 -B phone.py devices. The scoped read tools can then omit serial.

To enable tap_label, append "--allow-input" after the device arguments. The tool acts only on that configured phone and requires a single enabled clickable match for the exact accessibility label. Inspect the screen again after a tap to verify its effect.

Use a trusted local client and a test screen. Snapshots can contain private app content. Handle sensitive prompts manually and keep login, messaging, and payment screens out of the MCP workflow.

Client plugins

The Claude Code, Antigravity, Cursor, and Gemini CLI packages launch the same local MCP server. Before installing, put Node.js, uvx, and Android SDK Platform-Tools on the client's PATH and authorize a test device over ADB.

Open the plugin from this repository. In Claude Code, run claude --plugin-dir ./plugins/claude from a checkout. In Antigravity, use agy plugin install .. In Cursor, use Import from Disk in Customize. For Gemini CLI, install this repository with gemini extensions install https://github.com/lisn0/android-device-control.

Ask the client to list authorized Android devices, then inspect the foreground app on a test device. The plugin enables read-only inspection by default.

Workflows

The authentication guard uses English accessibility labels and password-field metadata. It can miss unlabeled or non-English screens. Handle passwords, verification codes, recovery, identity, and payment prompts directly on the device. Keep secrets out of command arguments and receipts.

Tests and bug reports

python3 -B -m unittest discover -s tests -v

The tests use mock ADB responses. For a bug report, provide the command, Android and ADB versions, and a sanitized error or synthetic reproduction. Device lists, snapshots, screenshots, and SMS output can contain serials, account identifiers, private messages, or codes. Remove those details before sharing.

License

MIT

Maintainer releases

Set the same version in pyproject.toml and package.json. Build and test the Python distributions and the npm archive from that source. Attach these three files to the stable GitHub release before publishing it.

  • android_device_control-X.Y.Z-py3-none-any.whl
  • android_device_control-X.Y.Z.tar.gz
  • android-device-control-X.Y.Z.tgz

Publishing the GitHub release with tag vX.Y.Z uploads the Python distributions to PyPI first and the npm launcher second. Both registries require a trusted publisher for publish-pypi.yml. The PyPI job uses the pypi environment.

To update the MCP Registry listing, match the versions in server.json to the published npm package. Push the manifest, then use mcp-publisher publish server.json from a machine authenticated to the official registry.

NPM
android-device-control
Install Command
npm install android-device-control
Runtime: npx