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

Integrations