android-control
by lisn0
README.md
# 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](https://pypi.org/project/android-device-control/) ·
[npm](https://www.npmjs.com/package/android-device-control) ·
[MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lisn0%2Fandroid-device-control/versions/latest)
[Install the CLI](#install) · [Run the MCP server](#run-the-mcp-server)
## Install
Python 3.10 or newer is required. Install `adb` from
[Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)
and put it on your PATH. In your Python environment, install the CLI.
```sh
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](https://developer.android.com/tools/adb)
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.
```sh
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.
```sh
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:
```sh
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
```sh
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.
```json
{
"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.
```sh
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`.
```json
{
"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](https://github.com/lisn0/android-device-control/blob/main/docs/workflows.md)
- [Device diagnostics and SMS inspection](https://github.com/lisn0/android-device-control/blob/main/docs/device-information.md)
- [Manual social-account setup and receipts](https://github.com/lisn0/android-device-control/blob/main/docs/social-account-setup.md)
- [Design references](https://github.com/lisn0/android-device-control/blob/main/docs/research.md)
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
```sh
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](https://github.com/lisn0/android-device-control/blob/main/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.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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues