KVM MCP サーバー

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

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

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

1. VM管理の簡素化：すべてのVM操作に単一の統合インターフェースを提供

2. リモートコントロールを有効にする: JSON-RPC 経由で VM のリモート管理を許可します

3. VM操作の自動化: VM管理タスクのスクリプト化と自動化を簡単に実現

4. VM構成の標準化: インフラストラクチャ全体で一貫したVM設定を確保

5. パフォーマンスの最適化: 効率的なリソース管理とキャッシュ戦略を実装する

Related MCP server: Model Coupling Platform Server

特徴

• 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ワークロードに十分なシステムリソース

インストール

1. このリポジトリをクローンします:

   git clone https://github.com/yourusername/kvm-mcp.git
   cd kvm-mcp

2. 仮想環境を作成してアクティブ化します。

   python3 -m venv .venv
   source .venv/bin/activate

3. 依存関係をインストールします:

   pip install -r requirements.txt

4. サーバーを構成します。

   • 環境に合わせてconfig.jsonを編集します

   • 必要なディレクトリがすべて存在することを確認する

   • ネットワークブリッジの構成を確認する

   • 必要に応じてパフォーマンス設定を調整する

使用法

1. サーバーを起動します。

   python3 kvm_mcp_server.py

2. 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 : 以前のログファイル（ローテーション済み）

• ログにはタイミング情報、接続プールのステータス、キャッシュのヒット/ミスが含まれます。

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

• 接続プールの使用状況統計

• キャッシュヒット/ミス比

• 操作タイミングメトリック

• リソース使用率統計

よくある問題と解決策

1. 接続プールの枯渇

   • 症状: 応答時間が遅い、または接続エラーが発生する

   • 解決策: 接続プール構成でmax_connectionsを増やす

2. キャッシュ無効化の問題

   • 症状: 古いVM情報

   • 解決策: no_cacheパラメータを使用するか、キャッシュTTLを減らす

3. リソースのクリーンアップ

   • 症状: リソースリークまたは接続の問題

   • 解決策: SIGTERM または SIGINT を使用して適切なシャットダウンを確実に行う

プロジェクト構造

• kvm_mcp_server.py : メインサーバーの実装

• config.json : 設定ファイル

• requirements.txt : Python の依存関係

• ルートディレクトリ内のサンプルスクリプト

• テストスイートはtests/ディレクトリにあります

貢献

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

ライセンス

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