Ubuntu Control MCP

Komplett Linux desktop agent MCP szerver. Nem csak „futtasd ezt a bash parancsot” – hanem „kezeld az Ubuntu gépet”: rendszerállapot, csomagkezelés, persistent terminálok (PTY / SSH), és teljes desktop control (egér, billentyűzet, ablakok, képernyőkép, OCR) – beépített, kétrétegű engedély-rendszerrel.

Lokális gép és tetszőleges számú távoli gép (SSH) egyszerre kezelhető.

Miért más, mint egy run_command(cmd) tool?

Related MCP server: Linux MCP Server

Engedély-modell

1. réteg – mód-kapu

A szerver egy módban fut (UBUNTU_CONTROL_MODE, alap: normal). Minden tool deklarálja a szükséges minimális módot; alacsonyabb módban meg sem próbál lefutni.

A mód lefelé bármikor állítható (set_mode), felfelé csak ADMIN-ból vagy induláskor a környezeti változóval – a modell nem tudja saját magát feljebb emelni.

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

A módtól függetlenül interaktív megerősítést kér (MCP elicitation) minden magas/közepes kockázatú művelet: rm -rf, mkfs/dd, reboot/shutdown, felhasználó-kezelés, tűzfal, apt purge/remove/upgrade, curl … | bash, rekurzív chmod/chown, fájl-felülírás, törlés, kényszerített ablak-bezárás, stb.

Ha a kliens nem támogatja az elicitet: a művelet elutasításra kerül, hacsak a UBUNTU_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), a nyilvánvaló titkok maszkolva.

Telepítés

git clone git@github.com:Scofield81/ubuntu-control-mcp.git
cd ubuntu-control-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[pty]"          # a [pty] extra a lokális terminálhoz kell (Linux)

Ellenőrzés:

ubuntu-control-mcp --list-tools

Ha ez kiírja a tool-listát, kész is vagy — irány a Futtatás szakasz.

Nincs SSH kulcsod a GitHub-hoz, vagy hibát kapsz a fenti lépések valamelyikén? A docs/INSTALL.md részletesen, lépésről lépésre leírja a letöltés minden módját (SSH kulcs beállítása, gh CLI, jelszó helyett token) és a leggyakoribb hibák elhárítását.

Desktop control a célgépen (opcionális, csak amire szükség van):

sudo apt install -y xdotool wmctrl scrot tesseract-ocr
# Wayland alatt: grim (képernyőkép). Az xdotool/wmctrl X11-et igényel (XWayland részleges).

Futtatás

UBUNTU_CONTROL_MODE=normal ubuntu-control-mcp

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

{
  "mcpServers": {
    "ubuntu-control": {
      "command": "/abszolut/ut/.venv/bin/ubuntu-control-mcp",
      "env": {
        "UBUNTU_CONTROL_MODE": "normal",
        "UBUNTU_CONTROL_SUDO_PASSWORD": "…",
        "UBUNTU_CONTROL_AUDIT_LOG": "~/.local/state/ubuntu-control-mcp/audit.log"
      }
    }
  }
}

HTTP transzport: UBUNTU_CONTROL_TRANSPORT=http UBUNTU_CONTROL_PORT=8000 ubuntu-control-mcp (a szerver 127.0.0.1-re köt).

Konfiguráció

Alap hely: ~/.config/ubuntu-control-mcp/config.json (vagy UBUNTU_CONTROL_CONFIG). Lásd config.example.json. A környezeti változók felülírják a fájlt: UBUNTU_CONTROL_MODE, UBUNTU_CONTROL_AUTO_APPROVE, UBUNTU_CONTROL_AUDIT_LOG, UBUNTU_CONTROL_DESKTOP_ENABLED, UBUNTU_CONTROL_SUDO_PASSWORD.

Titkok: a config fájl SOHA nem tárol jelszót. A hostoknál csak a környezeti változó nevét adod meg (password_env, sudo_password_env).

Távoli gépek

host_generate_key   → ed25519 kulcspár, a publikus kulcsot a távoli gépre másolod
host_add            → gép felvétele (name, hostname, username, key_path / *_env)
host_test           → kapcsolat + `id` / `uname -a`
host_list / host_remove

Ezután bármelyik tool host mezőjébe beírod a gép nevét; üresen hagyva a lokális gépen fut. Az első csatlakozáskor a host-kulcs trust-on-first-use módon elmentődik és auditálódik.

Tool-katalógus (kivonat)

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

Példák

„Frissítsd az Ubuntut.” apt_update → apt_list_upgradable (megmutatja) → (megerősítés) → apt_upgrade → hátralévő frissítések ellenőrzése

„Indítsd el a dev szervert és hagyd futni.” terminal_open → terminal_write("npm run dev\n") → terminal_wait(pattern="localhost:\\d+")

„SSH-zz be a prod gépre és nézd meg az api logját.” terminal_open(host="prod") → terminal_write("journalctl -u api -n 100 -f\n") → terminal_read

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

Fejlesztés

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

Kiértékelés: evaluation.xml – 10 kérdés, ami a szerver használhatóságát teszteli egy referencia Ubuntu környezeten.

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.