Skip to main content

Android Control

A local command-line tool for inspecting and operating an authorized Android device through ADB. Inspect the current app, select visible controls, and verify the result after each action. The repository includes read-only device and SMS diagnostics and a guide for manually setting up social accounts.

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.

Optional MCP server

An MCP client can launch Android Control locally over stdio. The server only needs the optional MCP SDK and access to adb on its PATH.

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.

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

Metadata

Release files for android-device-control 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for android-device-control 0.1.0
File Size Uploaded Provenance Actions
android_device_control-0.1.0.tar.gz 30.1 kB Without provenance Details for android_device_control-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for android-device-control 0.1.0
File Interpreter ABI Platform Actions
android_device_control-0.1.0-py3-none-any.whl Python 3 none any Details for android_device_control-0.1.0-py3-none-any.whl

Total release size: 53.7 kB

Release files / android_device_control-0.1.0.tar.gz

Download URL android_device_control-0.1.0.tar.gz
Size 30.1 kB
Tags Source
SHA-256 checksum
How to use checksums
95fb89da22ac25bc743cdf7407c1f5f08c90d1d540ddbd8406a554ecd6c7d1b3
BLAKE2b-256 checksum
How to use checksums
4da754a31dd45c6d4115ec19757629f1499c68a5fc94c1902aae01b3cf1d2ee0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / android_device_control-0.1.0-py3-none-any.whl

Download URL android_device_control-0.1.0-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b947d0752342d373415b0cd9676d84ff68fd1e08bdcd2150d5ab01e143ff6ae5
BLAKE2b-256 checksum
How to use checksums
ea72bfdc43d8ad728cddd435d360f14f1d785f03ce1ba231aa73947f0dff1fe8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for android-device-control 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page