
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
-
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.
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
- 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
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.whlandroid_device_control-X.Y.Z.tar.gzandroid-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.
android-device-controlnpm install android-device-control