Android Control MCP

Komplett Android eszköz-vezérlő MCP szerver. Nem csak „futtasd ezt az ADB parancsot” – hanem „kezeld a telefont/tabletet”: UI-automatizálás (koppintás, gépelés, gesztusok), képernyőkép/-felvétel, alkalmazáskezelés, fájlműveletek, naplók és értesítések – mindezt strukturált UI-hierarchiával, hogy a modellnek ne kelljen képfelismeréssel találgatnia, hova kell koppintani.

USB-n és vezeték nélküli (wifi) ADB-n keresztül is működik, tetszőleges számú csatlakoztatott eszközzel.

Fontos határ

Ez az eszköz nem képes és nem is célja képernyőzár vagy más hozzáférés-védelem jogosulatlan megkerülése. Minden funkció kizárólag olyan eszközön működik, amelyen a USB hibakeresés már korábban engedélyezve és jóváhagyva lett a készülék saját képernyőjén – ez az Android beépített biztonsági mechanizmusa, amit ez a szoftver szándékosan nem próbál megkerülni. Ha egy eszköz zárolt és sosem lett jóváhagyva, ez a szoftver sem tud vele mit kezdeni – ahogy semmi más, ami nem exploit/feltörő eszköz.

Related MCP server: Android Mobile MCP

Miért más, mint egy adb shell wrapper?

Engedély-modell

1. réteg – mód-kapu

A szerver egy módban fut (ANDROID_CONTROL_MODE, alap: normal).

2. réteg – kockázat-kapu (ask_permission)

A módtól függetlenül interaktív megerősítést kér minden visszafordíthatatlan/adatvesztéssel járó művelet: alkalmazás eltávolítása, alkalmazás adatainak törlése, ismeretlen APK telepítése, fájl/könyvtár törlése, bootloader/recovery újraindítás, tetszőleges shell parancs.

Ha a kliens nem támogatja az elicitet: a művelet elutasításra kerül, hacsak az ANDROID_CONTROL_AUTO_APPROVE=1 nincs bekapcsolva (csak zárt, megbízható környezetben).

Minden művelet auditálva van (stderr + opcionális naplófájl).

Telepítés

git clone git@github.com:Scofield81/android-control-mcp.git
cd android-control-mcp
python3 -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .

Ellenőrzés:

android-control-mcp --list-tools
android-control-mcp --devices

Nincs SSH kulcsod a GitHub-hoz, vagy hibát kapsz? → docs/INSTALL.md (letöltés minden módja, ADB telepítése/hibaelhárítás).

Előfeltétel: ADB

Az Android SDK Platform-Tools csomagban található adb binárisnak elérhetőnek kell lennie (PATH-ban, vagy add meg az ANDROID_CONTROL_ADB_PATH környezeti változóval). A telefonon/tableten pedig be kell kapcsolni: Beállítások → A telefonról → Szoftver-információ → koppints 7× a Buildszámra (fejlesztői mód bekapcsolása), majd Fejlesztői beállítások → USB hibakeresés.

Futtatás

ANDROID_CONTROL_MODE=normal android-control-mcp

MCP kliens (stdio) konfiguráció, pl. Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "android-control": {
      "command": "/abszolut/ut/.venv/bin/android-control-mcp",
      "env": {
        "ANDROID_CONTROL_MODE": "normal",
        "ANDROID_CONTROL_AUDIT_LOG": "~/.local/state/android-control-mcp/audit.log"
      }
    }
  }
}

Windows alatt a command a venv Scripts\android-control-mcp.exe útvonala.

HTTP transzport: ANDROID_CONTROL_TRANSPORT=http ANDROID_CONTROL_PORT=8001 android-control-mcp (a szerver 127.0.0.1-re köt).

Konfiguráció

Alap hely: ~/.config/android-control-mcp/config.json (vagy ANDROID_CONTROL_CONFIG). Lásd config.example.json. A környezeti változók felülírják a fájlt: ANDROID_CONTROL_MODE, ANDROID_CONTROL_AUTO_APPROVE, ANDROID_CONTROL_AUDIT_LOG, ANDROID_CONTROL_DEFAULT_SERIAL, ANDROID_CONTROL_ADB_PATH.

Tool-katalógus

Teljes lista: android-control-mcp --list-tools

Példák

„Nézd meg, milyen a telefon, és mennyi a szabad hely.” device_info → storage_usage → battery_status

„Nyisd meg a Beállításokat, és kapcsold be a repülő üzemmódot.” launch_app("com.android.settings") → ui_dump → tap a talált koordinátán → wait_for_text("Repülő") → tap

„Készíts képernyőképet, és mondd meg, mi van rajta.” screenshot → (a kép visszakerül a válaszban)

„Mentsd le a fotóimat a gépre.” list_files("/sdcard/DCIM/Camera") → pull_file minden fájlra

„Nézd meg, mit ír ki a logcat, amikor megnyitom az appot.” launch_app → rövid wait → logcat_tail

Fejlesztés

pip install -e ".[dev]"
python -m py_compile $(git ls-files '*.py')
ruff check .

Visszajelzés, hibajelentés, ötletek

Ha hibát találsz, vagy javaslatod van egy új funkcióhoz/tool-hoz, nyiss egy GitHub Issue-t ebben a repóban. Kód-hozzájárulást (pull request) egyelőre nem fogadunk — lásd CONTRIBUTING.md és a Licenc szakaszt.

Licenc

A forráskód nyilvánosan olvasható ezen a repón, de nem MIT/nyílt forráskódú licenc alatt áll. Letölthető, telepíthető és szabadon használható, de továbbterjesztése, kereskedelmi forgalomba hozatala és módosított változatának közzététele a szerző előzetes, írásos engedélye nélkül nem megengedett. A teljes feltételek: LICENSE.