Proxmoxmcp Plus

🚀 ProxmoxMCP-Plus - 拡張型Proxmox MCPサーバー

Pythonベースの拡張型Model Context Protocol (MCP)サーバーで、Proxmox仮想化プラットフォームとのインタラクションを可能にします。このプロジェクトは**canvrno/ProxmoxMCP**をベースに構築され、多数の新機能と改良が加えられており、完全なOpenAPI統合とより強力な仮想化管理機能を提供します。

謝辞

このプロジェクトは、@canvrnoによる優れたオープンソースプロジェクトProxmoxMCPをベースに構築されています。基礎となるフレームワークと創造的なインスピレーションを提供してくれた原作者に感謝します！

✨ 主な機能

旧バージョンに比べた主な強化点:

• ✨ 完全なVMライフサイクル管理

  • 全新のcreate_vmツール - カスタム構成での仮想マシンの作成をサポート
  • 新しいdelete_vmツール - 安全なVM削除（強制削除オプション付き）
  • 強化されたインテリジェントストレージタイプ検出（LVM/ファイルベース）

• 🔧 拡張された電源管理機能

  • start_vm - 仮想マシンの起動
  • stop_vm - 仮想マシンの強制停止
  • shutdown_vm - 正常なシャットダウン
  • reset_vm - 仮想マシンの再起動

• 🐳 新しいコンテナサポート

  • get_containers - すべてのLXCコンテナとその状態をリスト表示

• 📊 強化された監視と表示

  • 改善されたストレージプールの状態監視
  • より詳細なクラスタの健全性チェック
  • 豊富な出力形式とテーマ

• 🌐 完全なOpenAPI統合

  • 11の完全なREST APIエンドポイント
  • 本番環境で使用可能なDockerデプロイ
  • 完璧なOpen WebUI統合
  • 自然言語によるVM作成サポート

• 🛡️ 本番グレードのセキュリティと安定性

  • 強化されたエラーハンドリングメカニズム
  • 包括的なパラメータ検証
  • 本番レベルのロギング
  • 完全なユニットテストカバレッジ

構築に使用されたもの

• Cline - 自律的なコーディングエージェント - Clineで高速化
• Proxmoxer - Proxmox APIのPythonラッパー
• MCP SDK - Model Context Protocol SDK
• Pydantic - Pythonの型アノテーションを使用したデータ検証

📦 インストール

前提条件

• UVパッケージマネージャー（推奨）
• Python 3.9以上
• Git
• APIトークン資格情報を持つProxmoxサーバーへのアクセス

開始する前に、以下が必要です:

• [ ] Proxmoxサーバーのホスト名またはIP
• [ ] Proxmox APIトークン（Proxmox APIトークンの設定を参照）
• [ ] UVのインストール (pip install uv)

オプション1: クイックインストール（推奨）

1. リポジトリをクローンし、環境をセットアップします:

   # リポジトリをクローン
   git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
   cd ProxmoxMCP-Plus
   
   # 仮想環境を作成してアクティブ化
   uv venv
   source .venv/bin/activate  # Linux/macOS
   # OR
   .\.venv\Scripts\Activate.ps1  # Windows
   

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

   # 開発用依存関係を含めてインストール
   uv pip install -e ".[dev]"
   

3. 設定ファイルを作成します:

   # 設定ディレクトリを作成し、テンプレートをコピー
   mkdir -p proxmox-config
   cp proxmox-config/config.example.json proxmox-config/config.json
   

4. proxmox-config/config.jsonを編集します:

   {
       "proxmox": {
           "host": "PROXMOX_HOST",        # 必須: あなたのProxmoxサーバーのアドレス
           "port": 8006,                  # オプション: デフォルトは8006
           "verify_ssl": false,           # オプション: 自己署名証明書の場合はfalseに設定
           "service": "PVE"               # オプション: デフォルトはPVE
       },
       "auth": {
           "user": "USER@pve",            # 必須: あなたのProxmoxユーザー名
           "token_name": "TOKEN_NAME",    # 必須: APIトークンID
           "token_value": "TOKEN_VALUE"   # 必須: APIトークンの値
       },
       "logging": {
           "level": "INFO",               # オプション: より詳細な情報の場合はDEBUG
           "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
           "file": "proxmox_mcp.log"      # オプション: ログをファイルに保存
       }
   }
   

インストールの検証

1. Python環境を確認します:

   python -c "import proxmox_mcp; print('Installation OK')"
   

2. テストを実行します:

   pytest
   

3. 設定を検証します:

   # Linux/macOS
   PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server
   
   # Windows (PowerShell)
   $env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server
   

設定

Proxmox APIトークンの設定

1. Proxmoxのウェブインターフェイスにログインします。
2. データセンター -> パーミッション -> APIトークンに移動します。
3. 新しいAPIトークンを作成します:
   • ユーザーを選択します（例: root@pam）。
   • トークンIDを入力します（例: "mcp-token"）。
   • 完全なアクセス権を持たせる場合は「特権分離」をオフにします。
   • トークンIDとシークレットを保存し、コピーします。

サーバーの起動

開発モード

テストと開発用:

# 最初に仮想環境をアクティブ化
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# サーバーを起動
python -m proxmox_mcp.server

OpenAPIデプロイ（本番環境で使用可能）

ProxmoxMCP Plusを標準のOpenAPI RESTエンドポイントとしてデプロイし、Open WebUIや他のアプリケーションと統合します。

OpenAPIのクイックスタート

# mcpo (MCP-to-OpenAPIプロキシ)をインストール
pip install mcpo

# ポート8811でOpenAPIサービスを起動
./start_openapi.sh

Dockerデプロイ

# Dockerでビルドして実行
docker build -t proxmox-mcp-api .
docker run -d --name proxmox-mcp-api -p 8811:8811 \
  -v $(pwd)/proxmox-config:/app/proxmox-config proxmox-mcp-api

# またはDocker Composeを使用
docker-compose up -d

OpenAPIサービスへのアクセス

デプロイ後、以下のアドレスからサービスにアクセスできます:

• 📖 APIドキュメント: http://your-server:8811/docs
• 🔧 OpenAPI仕様: http://your-server:8811/openapi.json
• ❤️ ヘルスチェック: http://your-server:8811/health

Clineデスクトップの統合

Clineユーザーは、MCP設定ファイル（通常は~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）に以下の設定を追加します:

{
    "mcpServers": {
        "ProxmoxMCP-Plus": {
            "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP-Plus",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

利用可能なツールとAPIエンドポイント

サーバーは11の包括的なMCPツールと対応するREST APIエンドポイントを提供します:

VM管理ツール

create_vm

指定されたリソースで新しい仮想マシンを作成します。

パラメータ:

• node (文字列, 必須): ノードの名前
• vmid (文字列, 必須): 新しいVMのID
• name (文字列, 必須): VMの名前
• cpus (整数, 必須): CPUコアの数 (1-32)
• memory (整数, 必須): メモリ（MB） (512-131072)
• disk_size (整数, 必須): ディスクサイズ（GB） (5-1000)
• storage (文字列, オプション): ストレージプールの名前
• ostype (文字列, オプション): OSのタイプ (デフォルト: l26)

APIエンドポイント:

POST /create_vm
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "name": "my-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
}

応答例:

🎉 VM 200が正常に作成されました！

📋 VM構成:
  • 名前: my-vm
  • ノード: pve
  • VM ID: 200
  • CPUコア: 1
  • メモリ: 2048 MB (2.0 GB)
  • ディスク: 10 GB (local-lvm, raw形式)
  • ストレージタイプ: lvmthin
  • ネットワーク: virtio (bridge=vmbr0)
  • QEMUエージェント: 有効

🔧 タスクID: UPID:pve:001AB729:0442E853:682FF380:qmcreate:200:root@pam!mcp

VM電源管理 🆕

start_vm: 仮想マシンを起動します。

POST /start_vm
{"node": "pve", "vmid": "200"}

stop_vm: 仮想マシンを強制停止します。

POST /stop_vm
{"node": "pve", "vmid": "200"}

shutdown_vm: 仮想マシンを正常にシャットダウンします。

POST /shutdown_vm
{"node": "pve", "vmid": "200"}

reset_vm: 仮想マシンをリセット（再起動）します。

POST /reset_vm
{"node": "pve", "vmid": "200"}

delete_vm 🆕: 仮想マシンを完全に削除します。

POST /delete_vm
{"node": "pve", "vmid": "200", "force": false}

🆕 コンテナ管理ツール

get_containers 🆕

クラスタ全体のすべてのLXCコンテナをリスト表示します。

APIエンドポイント: POST /get_containers

応答例:

🐳 コンテナ

🐳 nginx-server (ID: 200)
  • 状態: RUNNING
  • ノード: pve
  • CPUコア: 2
  • メモリ: 1.5 GB / 2.0 GB (75.0%)

監視ツール

get_nodes

Proxmoxクラスタ内のすべてのノードをリスト表示します。

APIエンドポイント: POST /get_nodes

応答例:

🖥️ Proxmoxノード

🖥️ pve-compute-01
  • 状態: ONLINE
  • 稼働時間: ⏳ 156d 12h
  • CPUコア: 64
  • メモリ: 186.5 GB / 512.0 GB (36.4%)

get_node_status

特定のノードの詳細な状態を取得します。

パラメータ:

• node (文字列, 必須): ノードの名前

APIエンドポイント: POST /get_node_status

get_vms

クラスタ全体のすべてのVMをリスト表示します。

APIエンドポイント: POST /get_vms

get_storage

利用可能なストレージプールをリスト表示します。

APIエンドポイント: POST /get_storage

get_cluster_status

クラスタの全体的な状態と健全性を取得します。

APIエンドポイント: POST /get_cluster_status

execute_vm_command

QEMUゲストエージェントを使用してVMのコンソールでコマンドを実行します。

パラメータ:

• node (文字列, 必須): VMが実行されているノードの名前
• vmid (文字列, 必須): VMのID
• command (文字列, 必須): 実行するコマンド

APIエンドポイント: POST /execute_vm_command

要件:

• VMが実行中であること
• VM内にQEMUゲストエージェントがインストールされ、実行されていること

Open WebUIの統合

Open WebUIの設定

1. Open WebUIのインスタンスにアクセスします。
2. 設定 → 接続 → OpenAPIに移動します。
3. 新しいAPI設定を追加します:

{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "Enhanced Proxmox Virtualization Management API"
}

自然言語によるVM作成

ユーザーは自然言語でVMを要求することができます:

• "Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk"
• "Create a new VM for testing with minimal resources"
• "I need a development server with 4 cores and 8GB RAM"

AIアシスタントは自動的に適切なAPIを呼び出し、詳細なフィードバックを提供します。

ストレージタイプサポート

インテリジェントストレージ検出

ProxmoxMCP Plusは自動的にストレージタイプを検出し、適切なディスク形式を選択します:

LVMストレージ (local-lvm, vm-storage)

• ✅ 形式: raw
• ✅ 高性能
• ⚠️ クラウドイニシャライズイメージはサポートされていません

ファイルベースのストレージ (local, NFS, CIFS)

• ✅ 形式:qcow2
• ✅ クラウドイニシャライズサポート
• ✅ 柔軟なスナップショット機能

プロジェクト構造

ProxmoxMCP-Plus/
├── 📁 src/                          # ソースコード
│   └── proxmox_mcp/
│       ├── server.py                # 主要なMCPサーバーの実装
│       ├── config/                  # 設定の処理
│       ├── core/                    # コア機能
│       ├── formatting/              # 出力形式とテーマ
│       ├── tools/                   # ツールの実装
│       │   ├── vm.py               # VM管理 (作成/電源) 🆕
│       │   ├── container.py        # コンテナ管理 🆕
│       │   └── console/            # VMコンソール操作
│       └── utils/                   # ユーティリティ (認証, ロギング)
│
├── 📁 tests/                       # ユニットテストスイート
├── 📁 test_scripts/                # 統合テストとデモ
│   ├── README.md                   # テストドキュメント
│   ├── test_vm_power.py           # VM電源管理テスト 🆕
│   ├── test_vm_start.py           # VM起動テスト
│   ├── test_create_vm.py          # VM作成テスト 🆕
│   └── test_openapi.py            # OpenAPIサービステスト
│
├── 📁 proxmox-config/              # 設定ファイル
│   └── config.json                # サーバー設定
│
├── 📄 設定ファイル
│   ├── pyproject.toml             # プロジェクトメタデータ
│   ├── docker-compose.yml         # Dockerオーケストレーション
│   ├── Dockerfile                 # Dockerイメージ定義
│   └── requirements.in            # 依存関係
│
├── 📄 スクリプト
│   ├── start_server.sh            # MCPサーバー起動スクリプト
│   └── start_openapi.sh           # OpenAPIサービス起動スクリプト
│
└── 📄 ドキュメント
    ├── README.md                  # このファイル
    ├── VM_CREATION_GUIDE.md       # VM作成ガイド
    ├── OPENAPI_DEPLOYMENT.md      # OpenAPIデプロイメント
    └── LICENSE                    # MITライセンス

テスト

ユニットテストの実行

pytest

統合テストの実行

cd test_scripts

# VM電源管理テスト
python test_vm_power.py

# VM作成テスト
python test_create_vm.py

# OpenAPIサービステスト
python test_openapi.py

curlを使用したAPIテスト

# ノードリストのテスト
curl -X POST "http://your-server:8811/get_nodes" \
  -H "Content-Type: application/json" \
  -d "{}"

# VM作成のテスト
curl -X POST "http://your-server:8811/create_vm" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "pve",
    "vmid": "300",
    "name": "test-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
  }'

本番環境のセキュリティ

APIキー認証

安全なAPIアクセスを設定します:

export PROXMOX_API_KEY="your-secure-api-key"
export PROXMOX_MCP_CONFIG="/app/proxmox-config/config.json"

Nginxリバースプロキシ

Nginxの設定例:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8811;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

トラブルシューティング

一般的な問題

1. ポートが既に使用されている場合

   netstat -tlnp | grep 8811
   # 必要に応じてポートを変更
   mcpo --port 8812 -- ./start_server.sh
   

2. 設定エラーの場合

   # 設定ファイルを確認
   cat proxmox-config/config.json
   

3. 接続問題の場合

   # Proxmoxの接続性をテスト
   curl -k https://your-proxmox:8006/api2/json/version
   

ログの表示

# サービスログを表示
tail -f proxmox_mcp.log

# Dockerログを表示
docker logs proxmox-mcp-api -f

デプロイメント状況

✅ 機能の完了率: 100%

• [x] VM作成 (ユーザー要件: 1 CPU + 2GB RAM + 10GBストレージ) 🆕
• [x] VM電源管理 (VPNサーバーID:101の起動) 🆕
• [x] VM削除機能 🆕
• [x] コンテナ管理 (LXC) 🆕
• [x] ストレージ互換性 (LVM/ファイルベース)
• [x] OpenAPI統合 (ポート8811)
• [x] Open WebUI統合
• [x] エラーハンドリングと検証
• [x] 完全なドキュメントとテスト

本番環境での使用可能！

ProxmoxMCP Plusは現在、本番環境での使用が完全に可能です！

ユーザーが**"Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk"**と言った場合、AIアシスタントは以下のことができます:

1. 📞 create_vm APIを呼び出す
2. 🔧 自動的に適切なストレージと形式を選択する
3. 🎯 要件に合致するVMを作成する
4. 📊 詳細な構成情報を返す
5. 💡 次のステップの推奨事項を提供する

開発

仮想環境をアクティブ化した後:

• テストを実行する: pytest
• コードを整形する: black .
• 型チェックを行う: mypy .
• リントを実行する: ruff .

📄 ライセンス

MITライセンス

特別な感謝

• @canvrnoによる優れた基礎プロジェクトProxmoxMCPに感謝します。
• 強力な仮想化プラットフォームを提供してくれたProxmoxコミュニティに感謝します。
• サポートしてくれたすべての貢献者とユーザーに感謝します。

デプロイ準備完了！ 🎉 OpenAPI統合を備えた拡張型Proxmox MCPサービスが本番環境での使用を待っています。