KVM MCP サーバー

シンプルで直感的なインターフェースを通じてKVM仮想マシンを管理できる強力なJSON-RPCサーバーです。このサーバーは、標準化されたプロトコルを使用してKVM仮想マシンを集中的に制御・監視する方法を提供します。

なぜこのプロジェクトなのか?

KVM仮想マシンの管理には通常、 virsh 、 virt-install 、 qemu-systemといった複数のコマンドラインツールを使用する必要があります。このプロジェクトの目的は以下のとおりです。

VM管理の簡素化：すべてのVM操作に単一の統合インターフェースを提供
リモートコントロールを有効にする: JSON-RPC 経由で VM のリモート管理を許可します
VM操作の自動化: VM管理タスクのスクリプト化と自動化を簡単に実現
VM構成の標準化: インフラストラクチャ全体で一貫したVM設定を確保
パフォーマンスの最適化: 効率的なリソース管理とキャッシュ戦略を実装する

特徴

VMライフサイクル管理:
- カスタマイズ可能なパラメータを使用して新しいVMを作成する
- VMの起動/停止/再起動
- 利用可能なすべてのVMとそのステータスを一覧表示します
- 自動状態追跡と回復
ネットワーク管理:
- ブリッジを使用してVMネットワークを構成する
- brforvmsブリッジのサポート
- 自動ネットワークインターフェース構成
- IPアドレスの追跡と管理
ストレージ管理:
- 構成可能なVMディスクストレージの場所
- さまざまなディスク形式のサポート (qcow2)
- 設定可能なディスクサイズ
- 自動ディスククリーンアップと管理
ディスプレイ管理:
- グラフィカルアクセスのためのVNCサポート
- 自動VNCポート割り当て
- VMディスプレイを見つけて接続するためのツール
- ディスプレイの状態追跡と回復
インストールサポート：
- ISOイメージからのネットワークインストール
- CDROMからのローカルインストール
- さまざまなOSバリアントのサポート
- 自動インストール構成
パフォーマンスの最適化:
- 接続オーバーヘッドを削減するための libvirt の接続プール
- VM情報のキャッシュによる応答性の向上
- 並行性を向上させる非同期処理
- 診断とトラブルシューティングのための高度なログ記録
- 適切なリソースのクリーンアップのための正常なシャットダウン処理
- 自動接続回復と検証
- API操作のレート制限
- パフォーマンスメトリックの収集

パフォーマンス上の利点

接続プール

レイテンシの短縮: libvirt 接続を繰り返し開いたり閉じたりするオーバーヘッドを排除します。
リソース効率: 再利用可能な接続のプールを維持し、システムリソースの使用量を削減します。
自動回復: 切断された接続を自動的に検出して置き換えます
設定可能なプールサイズ: ワークロードに応じて接続数を調整します

キャッシング

応答時間の高速化: 一般的な操作に対する libvirt への繰り返しクエリを削減します。
設定可能なTTL : ニーズに応じてキャッシュの有効期限を設定します
選択的バイパス: 最新のデータを必要とする操作でキャッシュをバイパスするオプション
自動無効化: VMの状態が変化するとキャッシュは自動的に無効化されます

非同期処理

並行性の向上：複数のリクエストを同時に処理
リソース利用率の向上：システムリソースの効率的な使用
非ブロッキング操作: 長時間実行される操作はサーバーをブロックしません
正常なシャットダウン: シャットダウン時にリソースを適切にクリーンアップする

監視と診断

構造化ログ: 分析しやすいログ形式
パフォーマンスメトリクス: 操作のタイミングとリソースの使用状況を追跡する
エラー追跡: トラブルシューティングのための詳細なエラーログ
リソース監視: 接続プールの使用状況とキャッシュの有効性を追跡する

構成

サーバーは、デフォルト値とパスを保存するためにJSON設定ファイル（ config.json ）を使用します。これにより、サーバーの移植性が向上し、カスタマイズが容易になります。設定には以下が含まれます。

{ "vm": { "disk_path": "/vm", // Base directory for VM disk storage "default_iso": "/iso/ubuntu-24.04.2-live-server-amd64.iso", // Default installation media for Ubuntu-based VMs "default_master_image": "/iso/fedora-coreos-41-qemu.x86_64.qcow2", // Default base image for Fedora CoreOS VMs "default_name": "newvmname", // Default VM name "default_memory": 2048, // Default memory allocation in MB "default_vcpus": 2, // Default number of virtual CPUs "default_disk_size": 20, // Default disk size in GB "default_os_variant": "generic", // Default OS variant for virt-install "default_network": "brforvms", // Default network bridge for VM networking "ignition": { // Fedora CoreOS specific configuration "default_hostname": "coreos", // Default hostname for CoreOS VMs "default_user": "core", // Default user for CoreOS VMs "default_ssh_key": "~/.ssh/id_rsa.pub", // Default SSH public key path "default_timezone": "UTC", // Default timezone "default_locale": "en_US.UTF-8", // Default system locale "default_password_hash": null // Optional: Default password hash for user } } }

これらの値は、環境の要件に合わせて変更できます。設定では、次の形式を使用した環境変数のオーバーライドをサポートしています。

VM_DISK_PATH``disk_path用）
default_isoのVM_DEFAULT_ISO
default_master_imageのVM_DEFAULT_MASTER_IMAGE
default_nameのVM_DEFAULT_NAME
default_memoryのVM_DEFAULT_MEMORY
default_vcpusのVM_DEFAULT_VCPUS
default_disk_sizeのVM_DEFAULT_DISK_SIZE
default_os_variantのVM_DEFAULT_OS_VARIANT
default_networkのVM_DEFAULT_NETWORK
ignition.default_hostnameのVM_IGNITION_DEFAULT_HOSTNAME
ignition.default_userのVM_IGNITION_DEFAULT_USER
ignition.default_ssh_keyのVM_IGNITION_DEFAULT_SSH_KEY
ignition.default_timezoneのVM_IGNITION_DEFAULT_TIMEZONE
ignition.default_localeのVM_IGNITION_DEFAULT_LOCALE
ignition.default_password_hashのVM_IGNITION_DEFAULT_PASSWORD_HASH

パフォーマンスチューニング

接続プールの構成

connection_pool = LibvirtConnectionPool( max_connections=5, # Maximum number of connections in the pool timeout=30, # Timeout for getting a connection (seconds) uri='qemu:///system' # Libvirt connection URI )

キャッシュ構成

vm_info_cache = VMInfoCache( max_size=50, # Maximum number of VMs to cache ttl=60 # Time-to-live for cache entries (seconds) )

ログ構成

logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', handlers=[ RotatingFileHandler( 'kvm_mcp.log', maxBytes=10485760, # 10MB backupCount=5 ), logging.StreamHandler() ] )

はじめる

前提条件

Python 3.6以上
ホストシステムにKVMとlibvirtがインストールされている
構成されたネットワークブリッジ（デフォルト: brforvms ）
VM ストレージディレクトリが作成されました (デフォルト: /vm/ )
VMワークロードに十分なシステムリソース

インストール

このリポジトリをクローンします:
git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp
仮想環境を作成してアクティブ化します。
python3 -m venv .venv source .venv/bin/activate
依存関係をインストールします:
pip install -r requirements.txt
サーバーを構成します。
- 環境に合わせてconfig.jsonを編集します
- 必要なディレクトリがすべて存在することを確認する
- ネットワークブリッジの構成を確認する
- 必要に応じてパフォーマンス設定を調整する

使用法

サーバーを起動します。
python3 kvm_mcp_server.py
JSON-RPCを使用してコマンドを送信します。サンプルスクリプトが提供されています。
- create_vm.sh : デフォルト設定を使用して新しいVMを作成する
- get_vnc_ports.sh : 実行中のVMのVNCポートを見つける

コマンド例

新しいVMを作成する

./create_vm.sh

これにより、 config.jsonのデフォルト設定を使用して新しいVMが作成されます。これらのデフォルト設定は、リクエストで指定することで上書きできます。

VNCポートを見つける

./get_vnc_ports.sh

これにより、実行中のすべての VM とその VNC ポートが表示され、ディスプレイへの接続が容易になります。

キャッシュバイパスが有効なVMの一覧

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_vms", "arguments": {"no_cache": true}}, "id": 1}' | python3 kvm_mcp_server.py

監視とトラブルシューティング

ログファイル

kvm_mcp.log : 現在のログファイル
kvm_mcp.log.1 : 以前のログファイル（ローテーション済み）
ログにはタイミング情報、接続プールのステータス、キャッシュのヒット/ミスが含まれます。

パフォーマンスメトリック

接続プールの使用状況統計
キャッシュヒット/ミス比
操作タイミングメトリック
リソース使用率統計

よくある問題と解決策

接続プールの枯渇
- 症状: 応答時間が遅い、または接続エラーが発生する
- 解決策: 接続プール構成でmax_connectionsを増やす
キャッシュ無効化の問題
- 症状: 古いVM情報
- 解決策: no_cacheパラメータを使用するか、キャッシュTTLを減らす
リソースのクリーンアップ
- 症状: リソースリークまたは接続の問題
- 解決策: SIGTERM または SIGINT を使用して適切なシャットダウンを確実に行う

プロジェクト構造

kvm_mcp_server.py : メインサーバーの実装
config.json : 設定ファイル
requirements.txt : Python の依存関係
ルートディレクトリ内のサンプルスクリプト
テストスイートはtests/ディレクトリにあります

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。

KVM MCP Server