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
-
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.
-
List devices and run a read-only check. Replace
DEVICE_SERIALwith 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
- App navigation and UI interaction
- Device diagnostics and SMS inspection
- Manual social-account setup and receipts
- Design references
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.