The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Libvirt VMs and backups (Fedora) listing page.
English summary. MCP server that gives an AI agent hands on KVM/libvirt virtual machines and Borg/Timeshift backups on Fedora. Each tool declares whether it needs sudo and whether it is destructive; the client must confirm destructive calls. Arguments are validated with Zod before any script runs. Install with npx fedora-agents-mcp (--help lists the settings) or npm ci && npm run build. Security policy and tool table: SECURITY.md.
Serveur MCP (Model Context Protocol) qui expose les agents VM-Controller et Backup-Manager via le protocole MCP. Permet a Claude Code de gerer les VMs KVM et les backups directement.
Un script virsh suffit à un humain qui lit la sortie et réagit. Un agent LLM (grand
modèle de langage) qui pilote des machines a besoin d'autres garanties, et c'est ce que
ce serveur ajoute autour des scripts :
src/logger.ts).vm_status, backup_status, backup_list, backup_verify) sont retentées, trois fois
avec un délai croissant de 1, 2 puis 5 s ; une action qui modifie (démarrer, arrêter,
restaurer, nettoyer) ne l'est jamais. Une erreur de validation ou de permission arrête
tout de suite (src/utils/executor.ts).ErrorCode
lisible par l'agent, au lieu d'un texte à interpréter (EXIT_CODE_MAP, src/config.ts).virsh,
virt-clone ou qemu-img ; seuls les scripts système qui en ont besoin sont autorisés,
un par un (voir Emplacement des scripts et sudoers).scripts/utils/tracking.sh) : l'agent vérifie l'avancement plus tard au lieu de bloquer.readOnlyHint, destructiveHint, idempotentHint) ; Lyra y lit la
dangerosité et fait confirmer l'humain avant une action destructrice.Local-first et self-hosted : tout tourne sur la machine (on-prem), sans service tiers, avec un modèle local via Ollama dans Lyra ou n'importe quel client MCP.

Enregistree sur la machine reelle avec docs/demo/record.sh : un client MCP minimal (docs/demo/mcp_demo.py) demarre le serveur en stdio, liste les outils, appelle help puis vm_status (lecture seule). Les adresses IP sont remplacees par des adresses d'exemple.
Liste tous les outils disponibles avec leurs descriptions.
| Outil | Script sous-jacent | Description |
|---|---|---|
vm_start | vm-controller/vm-start.sh | Demarre une VM, attend optionnellement SSH |
vm_stop | vm-controller/vm-stop.sh | Arrete une VM (proprement ou force) |
vm_destroy | vm-controller/vm-destroy.sh | Supprime definition + stockage d'une VM |
vm_status | vm-controller/vm-status.sh | Affiche l'etat d'une VM (ou liste toutes) |
vm_exec | vm-controller/vm-exec.sh | Execute une commande dans une VM via SSH |
vm_copy | vm-controller/vm-copy.sh | Copie des fichiers hote <-> VM via SCP |
vm_snapshot | vm-controller/vm-snapshot.sh | Gere les snapshots (create/list/restore/delete) |
vm_verify | kvm/verify-vm-clone.sh | Verifie qu'un clone est fidele au systeme hote |
vm_clone | kvm/kvm-clone.sh | Clone une VM existante (complet ou lie) |
vm_clone_system | kvm/kvm-clone-system.sh | Clone le systeme hote entier vers une VM |
| Outil | Script sous-jacent | Description |
|---|---|---|
backup_status | backup-manager/backup-status.sh | Dashboard global des backups |
backup_list | backup-manager/backup-list.sh | Liste les backups disponibles |
backup_create | backup-manager/backup-create.sh | Cree un backup (timeshift/borg/vm-snapshot/manual) |
backup_verify | backup-manager/backup-verify.sh | Verifie l'integrite des backups |
backup_restore | backup-manager/backup-restore.sh | Restaure un backup (destructif) |
backup_clean | backup-manager/backup-clean.sh | Applique les politiques de retention |
| Outil | Script sous-jacent | Description |
|---|---|---|
vm_export | vm-controller/vm-export.sh | Exporte une VM en archive .tar.gz sanitarisee |
vm_import | vm-controller/vm-import.sh | Importe une VM depuis une archive vm_export |
Ces scripts sont utilises en interne mais pas directement accessibles via MCP:
| Script | Role |
|---|---|
agents/vm-controller/common.sh | Fonctions communes (virsh, SSH, logging) |
agents/backup-manager/common.sh | Fonctions communes (borg, locks, notifications) |
kvm/kvm-snapshot.sh | Moteur de snapshots appele par vm-snapshot.sh |
kvm/fix-nm-connection-vm.sh, kvm/_fix-grub-vm.sh | Corrections post-clone (NetworkManager, grub BLS) |
backup/borg-backup.sh, backup/get-borg-passphrase.sh | Sauvegarde Borg ; passphrase via systemd-creds ou Bitwarden, jamais en clair |
backup/test-restore.sh | Test de restauration utilise par backup-verify --deep |
src/config.ts resout la racine des scripts dans cet ordre :
LYRA_SCRIPTS_DIR (variable d'environnement)/usr/local/lib/lyra/scripts : copie root:root 0755 installee par l'installeur Lyrascripts/ du depot (mode developpement)Les outils sans sudo (vm_status, vm_start, vm_stop, vm_exec, vm_copy, vm_snapshot,
vm_export, vm_verify) pilotent libvirt directement : l'utilisateur doit etre membre du groupe
libvirt, que polkit autorise sur qemu:///system :
Aucune regle sudoers ne vise virsh, virt-clone ou qemu-img : un NOPASSWD sur ces binaires
equivaut a root (un domaine peut monter le disque de l'hote). Les outils qui demandent root
(vm_destroy, vm_clone, vm_clone_system, vm_import et les backup_*) lancent leur script
entier via sudo. Ces regles visent uniquement la copie systeme, script par script, jamais un
glob sur un dossier inscriptible par l'utilisateur (sinon n'importe quel processus de son uid obtient
root en y deposant un .sh) :
L'installeur Lyra genere ce fichier (/etc/sudoers.d/lyra) et le valide avec
visudo -cf avant de l'activer. Installation manuelle :
| Variable | Rôle | Défaut |
|---|---|---|
SCRIPTS_DIR | dossier des scripts (agents/, kvm/) : copie root pour la production, scripts/ du dépôt pour les tests | copie root installée par Lyra, sinon scripts/ |
MCP_AGENTS_LOG_DIR | journaux JSON (serveur, erreurs, audit des appels sous sudo ou destructifs) | /var/log/mcp-agents s'il est inscriptible, sinon $XDG_STATE_HOME/mcp-agents (~/.local/state/mcp-agents) ; fichiers en 0600, jamais dans /tmp |
scripts/config.env | chemins KVM, Borg, Timeshift (voir config.env.example) | valeurs d'exemple |
VM_SSH_USER, VM_SSH_USERS | compte SSH des VMs : par defaut, puis par VM ("fedora-base=fedora ubuntu-base=ubuntu"), dans config.env ou ~/.config/vm-controller/config | utilisateur courant |
Le serveur est un composant de Lyra mais fonctionne seul : SCRIPTS_DIR=./scripts node dist/index.js démarre sans sudoers (les outils marqués requiresSudo échoueront alors proprement).
src/config.ts (TIMEOUTS)src/config.ts (TOOL_PERMISSIONS)src/config.ts (RETRY_CONFIG)scripts/config.env (copier depuis scripts/config.env.example)Les logs JSON structures sont ecrits dans:
/var/log/mcp-agents/ (si accessible en ecriture)~/.local/state/mcp-agents/ (fallback utilisateur)/tmp/mcp-agents-logs/ (fallback final)Configuration Claude Desktop / Claude Code (mcpServers) :
Politique de securite et tableau des outils : SECURITY.md.
Paquets a installer sur l'hote (noms Fedora ; Debian/Ubuntu entre parentheses quand ils different) :
| Commande | Paquet | Outils concernes |
|---|---|---|
virsh | libvirt-client (libvirt-clients) | tous les vm_* |
virt-clone | virt-install (virtinst) | vm_clone |
virt-install | virt-install (virtinst) | vm_clone_system |
qemu-img | qemu-img (qemu-utils) | vm_status, vm_clone, vm_clone_system, vm_import, vm_export, vm_destroy |
guestfish | guestfs-tools (libguestfs-tools) | vm_clone (reseau et GRUB du clone) |
ssh, scp | openssh-clients (openssh-client) | vm_exec, vm_copy, vm_clone (nom d'hote du clone) |
borg | borgbackup | backup_*, vm_export |
timeshift | timeshift | backup_*, vm_clone_system |
rsync | rsync | backup_create, backup_list, backup_restore, vm_clone_system |
nmap (optionnel) | nmap | vm_verify, vm_clone (recherche d'IP sans agent invite) |
| Node.js >= 18 | nodejs | le serveur MCP |
Les cles d'hote SSH des VMs sont conservees dans $XDG_STATE_HOME/fedora-agents/known_hosts (a defaut ~/.local/state/fedora-agents/known_hosts) : premier contact accepte, cle modifiee refusee.
La configuration MCP pour Claude Code ou Claude Desktop est decrite dans la section Installation en une ligne.
| Dépôt | Rôle |
|---|---|
| lyra | French-first voice assistant : assistant DevOps vocal, local par défaut (AGPL-3.0) ; le français familier est compris par des règles avant même d'appeler un modèle, ce qui lui suffit d'un modèle de 0.5B |
| fedora-agents | MCP : machines virtuelles KVM et sauvegardes |
| mcp-tracking | MCP + API + tableau de bord des tâches longues |
| neutroncore | hub PWA du homelab |
| hue-mcp | MCP Philips Hue (fork de ThomasRohde/hue-mcp) |
| pylips-mcp | MCP TV Philips |
| denon-mcp | MCP ampli Denon |
| catt-mcp | MCP Chromecast et DLNA |