Cursor Proxmox MCP

🚀 cursor-proxmox-mcp - オプションでOpenAPIを備えたCursor用Proxmox MCPサーバー

Cursorに特化した、Pythonベースのモデルコンテキストプロトコル（MCP）サーバーです。Proxmox仮想化プラットフォームとの相互作用に関する修正と機能強化が施されています。

🆕 新機能と改善点

全てのテストがパス

• 以前はテストが完了しない問題がありましたが、修正しました。

継続的なサポート

• 私自身のProxmoxインスタンスを管理するためにこのプロジェクトを必要としているため、必要に応じて更新と変更を公開し続けます。

オリジナルバージョンと比較した主要な機能強化点:

• ✨ 完全な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作成サポート

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

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

構築に使用された技術

• Cursor
• Proxmoxer - Proxmox APIのPythonラッパー
• MCP SDK - モデルコンテキストプロトコルSDK
• Pydantic - Pythonの型アノテーションを使用したデータ検証

機能

• 🤖 CursorとOpen WebUIとの完全統合
• 🛠️ 公式MCP SDKを使用して構築
• 🔒 Proxmoxとの安全なトークンベースの認証
• 🖥️ 完全なVMライフサイクル管理（作成、起動、停止、再起動、シャットダウン、削除）
• 💻 VMコンソールコマンドの実行
• 🐳 LXCコンテナ管理サポート
• 🗃️ ストレージタイプの自動検出（LVM/ファイルベース）
• 📝 設定可能なロギングシステム
• ✅ Pydanticによる型安全な実装
• 🎨 カスタマイズ可能なテーマを持つ豊富な出力形式
• 🌐 統合用のOpenAPI RESTエンドポイント
• 📡 11の完全に機能するAPIエンドポイント

📦 インストール

前提条件

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

インストールを開始する前に、以下が必要です:

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

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

1. リポジトリをクローンし、環境を設定します:

   # リポジトリをクローン
   git clone https://github.com/agentify-sh/cursor-proxmox-mcp.git
   cd ProxmoxMCP-Plus
   
   # 仮想環境を作成してアクティブ化
   uv venv
   
   # または、3.11を強制的に使用する（mcpo依存のため）
   python3.11 -m venv .venv
   
   # その後、仮想環境をアクティブ化
   source .venv/bin/activate  # Linux/macOS
   # または
   .\.venv\Scripts\Activate.ps1  # Windows
   

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

   # 開発用依存関係を含めてインストール
   uv pip install -e ".[dev]"
   
   # またはpipを使用してインストール
   pip install -e .
   pip install pytest pytest-asyncio black mypy ruff types-requests
   pip install mcpo # Python 3.11が必要
   

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のWebインターフェースにログインします。
2. データセンター -> 権限 -> APIトークンに移動します。
3. 新しいAPIトークンを作成します:
   • ユーザーを選択します（例: root@pam）。
   • トークンIDを入力します（例: "mcp-token"）。
   • 完全なアクセス権を必要とする場合は、「特権分離」をオフにします。
   • 保存し、トークンIDとシークレットをコピーします。

サーバーの起動

開発モード

テストと開発用には、以下の手順でサーバーを起動します:

# まず仮想環境をアクティブ化
source .venv/bin/activate  # Linux/macOS
# または
.\.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サービスへのアクセス

デプロイが完了したら、以下のURLからサービスにアクセスできます:

• 📖 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, 生形式)
  • ストレージタイプ: 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
  • 稼働時間: ⏳ 156日 12時間
  • 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": "強化されたProxmox仮想化管理API"
}

自然言語によるVM作成

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

• "1つのCPUコアと2GBのRAM、10GBのストレージディスクを持つVMを作成できますか？"
• "最小限のリソースでテスト用の新しいVMを作成してください。"
• "4コアと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は現在、本番環境での使用が完全に可能です！

ユーザーが "1つのCPUコアと2GBのRAM、10GBのストレージディスクを持つVMを作成できますか？" と言った場合、AIアシスタントは以下のことができます:

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

開発

仮想環境をアクティブ化した後は、以下のコマンドを使用できます:

• テストの実行: pytest
• コードのフォーマット: black .
• 型チェック: mypy .
• リント: ruff .

📄 ライセンス

MITライセンス

謝辞

このプロジェクトは、@RekklesNAによる優れたオープンソースプロジェクトProxmoxMCPをベースに構築されています。元の作者が基本的なフレームワークと創造的なインスピレーションを提供してくれたことに感謝します！私はCursor IDEでの使用に特化してこのプロジェクトを更新し続けます。

特別な感謝

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

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