KVM/libvirt VMs and backups (Fedora) について
KVM/libvirt VMs and backups (Fedora) は、Fedora 上の KVM/libvirt 仮想マシンと Borg または Timeshift のバックアップを管理するローカル MCP サーバーです。ツールごとの権限や破壊的操作を示し、引数を検証して呼び出しを監査記録します。
主な機能
- 01VM の起動、停止、複製、状態確認
- 02VM スナップショットと転送の管理
- 03バックアップの作成、復元、検証
- 04Zod によるツール引数の検証
- 05呼び出しの監査と破壊的操作の明示
活用シーン
- 01Fedora 上の KVM 仮想マシンの運用
- 02Borg または Timeshift バックアップの作成と復元
- 03破壊的操作の前のリスク確認
MCP 対応
VM とバックアップを管理するツールを MCP クライアントに公開します。状態確認、複製、スナップショット、バックアップ操作に対応し、ツール注釈で破壊的操作や読み取り専用の性質を示します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
19掲載時のツール一覧 · 2 週間前に更新
このツールにパラメーターはありません。
詳細
fedora-agents MCP Server
英語での概要。 Fedora 上の KVM/libvirt 仮想マシンと Borg/Timeshift バックアップを AI エージェントが直接操作できる MCP サーバーです。各ツールは sudo が必要か、破壊的な操作かを明示し、破壊的な呼び出しにはクライアントによる確認が必要です。スクリプトを実行する前に、引数を Zod で検証します。npx fedora-agents-mcp（設定の一覧は --help）または npm ci && npm run build でインストールできます。セキュリティポリシーとツール一覧については、SECURITY.md を参照してください。
MCP（Model Context Protocol）を介して VM-Controller エージェントと Backup-Manager エージェントを公開する MCP サーバーです。Claude Code で KVM 仮想マシンとバックアップを直接管理できます。
LLM エージェント向けに設計されている理由
出力を読んで対処する人間であれば、virsh スクリプトだけで十分です。マシンを操作する LLM エージェントには、別の保証が必要です。このサーバーは、スクリプトの周囲に次の保証を追加します。
- すべての呼び出しを追跡できます。 ツール呼び出しごとに相関 ID が作成され、すべてのログ行に引き継がれます。JSON 監査ログは同期的にディスクへ書き込まれ、エージェントへの応答前に記録されます（
src/logger.ts）。 - 再試行はツールの性質に応じて行われます。 再試行されるのは、冪等な読み取り（
vm_status、backup_status、backup_list、backup_verify）だけです。間隔を 1、2、5 秒と延ばしながら、最大 3 回再試行します。変更を伴う操作（起動、停止、復元、クリーンアップ）は再試行されません。検証エラーや権限エラーが発生した場合は、ただちに停止します（src/utils/executor.ts）。 - 終了コードを型付きエラーに変換します。 スクリプトが返すコード（タイムアウト、ロック取得済み、容量不足など）を、サーバーがエージェントにとって分かりやすい
ErrorCodeに変換し、解釈が必要なテキストを返しません（EXIT_CODE_MAP、src/config.ts）。 - root 権限はスクリプトごとに付与します。
virsh、virt-clone、qemu-imgに対する sudoers ルールはありません。必要なシステムスクリプトだけを、個別に許可します（スクリプトと sudoers の場所 を参照）。 - 時間のかかるタスクの進捗を公開します。 クローン、エクスポート、バックアップの各ステップを mcp-tracking（
scripts/utils/tracking.sh）に報告します。エージェントは処理をブロックせず、後から進捗を確認できます。 - クライアントは、管理リストなしで危険な操作を把握できます。 各ツールは MCP アノテーション（
readOnlyHint、destructiveHint、idempotentHint）を公開します。Lyra はそれらから危険性を読み取り、破壊的な操作の前に人間へ確認を求めます。
ローカルファーストでセルフホスト可能です。すべてがマシン上（オンプレミス）で動作し、サードパーティーのサービスは不要です。Lyra の Ollama によるローカルモデル、または任意の MCP クライアントを利用できます。
デモ
実機で docs/demo/record.sh を使って録画しました。最小限の MCP クライアント（docs/demo/mcp_demo.py）が stdio でサーバーを起動し、ツールを一覧表示してから、help、続いて vm_status（読み取り専用）を呼び出します。IP アドレスはサンプルのアドレスに置き換えています。
アーキテクチャ
fedora-agents/
scripts/ -- scripts bash embarques (autonomes, plus de dependance a fedora-setup)
agents/vm-controller/ vm-start, vm-stop, vm-status, vm-exec, vm-copy, vm-snapshot,
vm-destroy, vm-export, vm-import (+ common.sh)
agents/backup-manager/ backup-create, backup-list, backup-restore, backup-verify,
backup-clean, backup-status (+ common.sh)
kvm/ kvm-clone, kvm-clone-system, kvm-snapshot, verify-vm-clone
(+ helpers fix-nm-connection-vm, _fix-grub-vm)
backup/ borg-backup, test-restore, get-borg-passphrase
utils/tracking.sh reporting optionnel vers MCP Tracking (127.0.0.1:8765)
config.env.example surcharges locales (KVM_IMAGES_DIR, VM_SSH_USER...)
src/
index.ts -- point d'entree, enregistrement des outils MCP
config.ts -- timeouts, permissions, codes d'erreur
logger.ts -- logging JSON structure
tools/
vm-controller.ts -- outils vm_start, vm_stop, vm_status, vm_exec, vm_copy,
vm_snapshot, vm_verify, vm_clone, vm_clone_system, vm_destroy
backup-manager.ts -- outils backup_create, backup_list, backup_restore,
backup_verify, backup_clean, backup_status
vm-portability.ts -- outils vm_export, vm_import
utils/
executor.ts -- execution des scripts bash avec retry, timeout, gestion erreurs
validation.ts -- schemas Zod pour tous les parametres d'outils
公開されている MCP ツール
help
利用可能なすべてのツールとその説明を一覧表示します。
- 基盤となるスクリプト：なし（
index.ts内で直接生成）
VM コントローラー
| ツール | 基になるスクリプト | 説明 |
|---|---|---|
vm_start | vm-controller/vm-start.sh | VM を起動し、必要に応じて SSH を待機します |
vm_stop | vm-controller/vm-stop.sh | VM を停止します（正常または強制） |
vm_destroy | vm-controller/vm-destroy.sh | VM の定義とストレージを削除します |
vm_status | vm-controller/vm-status.sh | VM の状態を表示します（またはすべて一覧表示します） |
vm_exec | vm-controller/vm-exec.sh | SSH 経由で VM 内のコマンドを実行します |
vm_copy | vm-controller/vm-copy.sh | SCP 経由でホストと VM 間のファイルをコピーします |
vm_snapshot | vm-controller/vm-snapshot.sh | スナップショットを管理します（作成／一覧表示／復元／削除） |
vm_verify | kvm/verify-vm-clone.sh | クローンがホストシステムを忠実に再現しているか検証します |
vm_clone | kvm/kvm-clone.sh | 既存の VM をクローンします（フルまたはリンク） |
vm_clone_system | kvm/kvm-clone-system.sh | ホストシステム全体を VM にクローンします |
バックアップマネージャー
| ツール | 基になるスクリプト | 説明 |
|---|---|---|
backup_status | backup-manager/backup-status.sh | バックアップ全体のダッシュボード |
backup_list | backup-manager/backup-list.sh | 利用可能なバックアップを一覧表示します |
backup_create | backup-manager/backup-create.sh | バックアップを作成します（timeshift／borg／vm-snapshot／manual） |
backup_verify | backup-manager/backup-verify.sh | バックアップの整合性を検証します |
backup_restore | backup-manager/backup-restore.sh | バックアップを復元します（破壊的操作） |
backup_clean | backup-manager/backup-clean.sh | 保持ポリシーを適用します |
VM のポータビリティ
| ツール | 基になるスクリプト | 説明 |
|---|---|---|
vm_export | vm-controller/vm-export.sh | VM をサニタイズ済みの .tar.gz アーカイブとしてエクスポートします |
vm_import | vm-controller/vm-import.sh | vm_export アーカイブから VM をインポートします |
公開されていないヘルパースクリプト
これらのスクリプトは内部で使用されますが、MCP 経由では直接アクセスできません。
| スクリプト | 役割 |
|---|---|
agents/vm-controller/common.sh | 共通関数（virsh、SSH、ロギング） |
agents/backup-manager/common.sh | 共通関数（borg、ロック、通知） |
kvm/kvm-snapshot.sh | vm-snapshot.sh から呼び出されるスナップショットエンジン |
kvm/fix-nm-connection-vm.sh, kvm/_fix-grub-vm.sh | クローン後の修正（NetworkManager、grub BLS） |
backup/borg-backup.sh, backup/get-borg-passphrase.sh | Borg バックアップ。パスフレーズは systemd-creds または Bitwarden 経由で取得し、平文では決して保存しません |
backup/test-restore.sh | backup-verify --deep で使用される復元テスト |
スクリプトの場所と sudoers
src/config.ts は次の順序でスクリプトのルートディレクトリを解決します。
LYRA_SCRIPTS_DIR（環境変数）/usr/local/lib/lyra/scripts：Lyra インストーラーがインストールするroot:root 0755のコピー- リポジトリ内の
scripts/（開発モード）
sudo を使わないツール（vm_status、vm_start、vm_stop、vm_exec、vm_copy、vm_snapshot、
vm_export、vm_verify）は libvirt を直接操作します。ユーザーは libvirt グループに所属している必要があり、polkit によって qemu:///system へのアクセスが許可されます。
sudo usermod -aG libvirt "$USER" # puis se reconnecter
virsh -c qemu:///system list --all # doit repondre sans sudo
virsh、virt-clone、qemu-img を対象とする sudoers ルールはありません。これらのバイナリに対する NOPASSWD は root 権限と同等です（ドメインからホストのディスクをマウントできるためです）。root 権限を必要とするツール（vm_destroy、vm_clone、vm_clone_system、vm_import、および backup_*）は、スクリプト全体を sudo 経由で実行します。これらのルールは、システムコピー内のスクリプトを一つずつ個別に対象とし、ユーザーが書き込み可能なディレクトリに対する glob は決して使用しません（使用すると、ユーザーの UID で実行される任意のプロセスがそこに .sh を置くだけで root 権限を取得できてしまいます）。
user ALL=(ALL) NOPASSWD: /usr/local/lib/lyra/scripts/kvm/kvm-clone.sh
user ALL=(ALL) NOPASSWD: /usr/local/lib/lyra/scripts/kvm/kvm-clone-system.sh
...
Lyra インストーラーはこのファイル（/etc/sudoers.d/lyra）を生成し、有効化する前に
visudo -cf で検証します。手動でのインストール：
sudo install -d -o root -g root -m 0755 /usr/local/lib/lyra/scripts
sudo cp -r scripts/. /usr/local/lib/lyra/scripts/
sudo chown -R root:root /usr/local/lib/lyra/scripts
sudo find /usr/local/lib/lyra/scripts -type f -name '*.sh' -exec chmod 0755 {} +
設定
| 変数 | 役割 | デフォルト |
|---|---|---|
SCRIPTS_DIR | スクリプトのディレクトリ（agents/, kvm/）：本番環境ではインストール先ルートのコピー、テストではリポジトリの scripts/ | Lyra によってインストールされたルートのコピー、それ以外は scripts/ |
MCP_AGENTS_LOG_DIR | JSON ログ（サーバー、エラー、sudo または破壊的な呼び出しの監査） | 書き込み可能なら /var/log/mcp-agents、そうでなければ $XDG_STATE_HOME/mcp-agents（~/.local/state/mcp-agents）；ファイルの権限は 0600、/tmp には保存しません |
scripts/config.env | KVM、Borg、Timeshift のパス（config.env.example を参照） | サンプル値 |
VM_SSH_USER、VM_SSH_USERS | VM の SSH アカウント：デフォルト値の後に VM ごとの値（"fedora-base=fedora ubuntu-base=ubuntu"）を指定し、config.env または ~/.config/vm-controller/config に記述します | 現在のユーザー |
このサーバーは Lyra のコンポーネントですが、単独でも動作します：SCRIPTS_DIR=./scripts node dist/index.js で sudoers 設定なしに起動できます（requiresSudo とマークされたツールは適切に失敗します）。
- タイムアウト：
src/config.ts（TIMEOUTS） - sudo 権限：
src/config.ts（TOOL_PERMISSIONS） - リトライ：
src/config.ts（RETRY_CONFIG） - ローカル設定：
scripts/config.env（scripts/config.env.exampleからコピー）
ログ
構造化 JSON ログは次の場所に書き込まれます：
/var/log/mcp-agents/（書き込み可能な場合）~/.local/state/mcp-agents/（ユーザー用フォールバック）/tmp/mcp-agents-logs/（最終フォールバック）
1 行でインストール
npx fedora-agents-mcp # depuis npm ; `npx fedora-agents-mcp --help` pour les reglages
# depuis un clone : npm ci && npm run build && node dist/index.js
Claude Desktop / Claude Code の設定（mcpServers）：
{ "fedora-agents": { "command": "npx", "args": ["-y", "fedora-agents-mcp"] } }
セキュリティポリシーとツール一覧：SECURITY.md。
インストールと起動
ホストにインストールするパッケージ（Fedora のパッケージ名。異なる場合は Debian/Ubuntu の名前を括弧内に記載）：
| コマンド | パッケージ | 対象ツール |
|---|---|---|
virsh | libvirt-client（libvirt-clients） | すべての 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（クローンのネットワークと GRUB） |
ssh、scp | openssh-clients（openssh-client） | vm_exec、vm_copy、vm_clone（クローンのホスト名） |
borg | borgbackup | backup_*、vm_export |
timeshift | timeshift | backup_*、vm_clone_system |
rsync | rsync | backup_create、backup_list、backup_restore、vm_clone_system |
nmap（任意） | nmap | vm_verify、vm_clone（ゲストエージェントなしで IP を検索） |
| Node.js >= 18 | nodejs | MCP サーバー |
VM の SSH ホスト鍵は $XDG_STATE_HOME/fedora-agents/known_hosts（未設定の場合は ~/.local/state/fedora-agents/known_hosts）に保存されます：初回接続時は受け入れ、変更された鍵は拒否します。
npm install
npm run build
# Test local (scripts/ du depot, sans sudoers)
node dist/index.js
Claude Code または Claude Desktop の MCP 設定については、 1 行でインストールのセクションを参照してください。
Lyra エコシステムの一部
| リポジトリ | 役割 |
|---|---|
| lyra | フランス語優先の音声アシスタント：DevOps 音声アシスタントで、デフォルトではローカルで動作します（AGPL-3.0）；くだけたフランス語はモデルを呼び出す前にルールで理解できるため、0.5B のモデルで十分です |
| fedora-agents | MCP：KVM 仮想マシンとバックアップ |
| mcp-tracking | MCP + API + 長時間実行タスクのダッシュボード |
| neutroncore | ホームラボの PWA ハブ |
| hue-mcp | Philips Hue 用 MCP（ThomasRohde/hue-mcp のフォーク） |
| pylips-mcp | Philips TV 用 MCP |
| denon-mcp | Denon アンプ用 MCP |
| catt-mcp | Chromecast と DLNA 用 MCP |
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。