🚀 Proxmox マネージャー - Proxmox MCP サーバー

Proxmox ハイパーバイザーと対話するための Python ベースの Model Context Protocol (MCP) サーバー。ノード、VM、コンテナを管理するためのクリーンなインターフェースを提供します。

🏗️ で構築

• Cline - 自律コーディングエージェント - Cline でスピードアップ。

• Proxmoxer - Proxmox API の Python ラッパー

• MCP SDK - モデルコンテキストプロトコル SDK

• Pydantic - Python 型アノテーションを使用したデータ検証

Related MCP server: nandi-proxmox-mcp

✨ 特徴

• 🤖 Clineとの完全な統合

• 🛠️ 公式MCP SDKで構築

• 🔒 Proxmoxによる安全なトークンベースの認証

• 🖥️ ノードとVMを管理するためのツール

• 💻 VMコンソールコマンド実行

• 📝 設定可能なログシステム

• ✅ Pydantic による型安全な実装

• 🎨 カスタマイズ可能なテーマによる豊富な出力フォーマット

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 インストール

前提条件

• UV パッケージ マネージャー (推奨)

• Python 3.10以上

• ギット

• APIトークン認証情報を使用したProxmoxサーバーへのアクセス

始める前に、次のものを用意してください。

• [ ] Proxmoxサーバーのホスト名またはIP

• [ ] Proxmox APIトークン（ APIトークンの設定を参照）

• [ ] UVがインストールされました（ pip install uv ）

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

1. 環境のクローンとセットアップ:

   # Clone repository
   cd ~/Documents/Cline/MCP  # For Cline users
   # OR
   cd your/preferred/directory  # For manual installation
   
   git clone https://github.com/canvrno/ProxmoxMCP.git
   cd ProxmoxMCP
   
   # Create and activate virtual environment
   uv venv
   source .venv/bin/activate  # Linux/macOS
   # OR
   .\.venv\Scripts\Activate.ps1  # Windows

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

   # Install with development dependencies
   uv pip install -e ".[dev]"

3. 構成を作成します。

   # Create config directory and copy template
   mkdir -p proxmox-config
   cp config/config.example.json proxmox-config/config.json

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

   {
       "proxmox": {
           "host": "PROXMOX_HOST",        # Required: Your Proxmox server address
           "port": 8006,                  # Optional: Default is 8006
           "verify_ssl": false,           # Optional: Set false for self-signed certs
           "service": "PVE"               # Optional: Default is PVE
       },
       "auth": {
           "user": "USER@pve",            # Required: Your Proxmox username
           "token_name": "TOKEN_NAME",    # Required: API token ID
           "token_value": "TOKEN_VALUE"   # Required: API token value
       },
       "logging": {
           "level": "INFO",               # Optional: DEBUG for more detail
           "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
           "file": "proxmox_mcp.log"      # Optional: Log to file
       }
   }

インストールの確認

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サーバーへの接続に成功しました

   • または接続エラー（Proxmoxの詳細が正しくない場合）

⚙️ 構成

Proxmox APIトークンの設定

1. Proxmoxウェブインターフェースにログインする

2. データセンター -> 権限 -> APIトークンに移動します

3. 新しい API トークンを作成します。

   • ユーザーを選択します（例：root@pam）

   • トークンIDを入力します（例：「mcp-token」）

   • フルアクセスが必要な場合は「権限分離」のチェックを外してください

   • トークンIDとシークレットの両方を保存してコピーします

🚀 サーバーの実行

開発モード

テストと開発の場合:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

Clineデスクトップ統合

Cline ユーザーの場合は、次の構成を MCP 設定ファイル (通常は~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ) に追加します。

{
    "mcpServers": {
        "github.com/canvrno/ProxmoxMCP": {
            "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/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": []
        }
    }
}

正しいパスを生成するには、次のコマンドを使用できます。

# This will print the MCP settings with your absolute paths filled in
python -c "import os; print(f'''{{
    \"mcpServers\": {{
        \"github.com/canvrno/ProxmoxMCP\": {{
            \"command\": \"{os.path.abspath('.venv/bin/python')}\",
            \"args\": [\"-m\", \"proxmox_mcp.server\"],
            \"cwd\": \"{os.getcwd()}\",
            \"env\": {{
                \"PYTHONPATH\": \"{os.path.abspath('src')}\",
                \"PROXMOX_MCP_CONFIG\": \"{os.path.abspath('proxmox-config/config.json')}\",
                ...
            }}
        }}
    }}
}}''')"

重要：

• すべてのパスは絶対パスである必要があります

• Pythonインタープリタは仮想環境から取得する必要があります

• PYTHONPATHはsrcディレクトリを指している必要があります

• MCP設定を更新した後、VSCodeを再起動します。

🔧 利用可能なツール

サーバーは、Proxmox と対話するための次の MCP ツールを提供します。

get_nodes

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

• パラメータ: なし

• 応答例:

  🖥️ Proxmox Nodes
  
  🖥️ pve-compute-01
    • Status: ONLINE
    • Uptime: ⏳ 156d 12h
    • CPU Cores: 64
    • Memory: 186.5 GB / 512.0 GB (36.4%)
  
  🖥️ pve-compute-02
    • Status: ONLINE
    • Uptime: ⏳ 156d 11h
    • CPU Cores: 64
    • Memory: 201.3 GB / 512.0 GB (39.3%)

ノードステータスの取得

特定のノードの詳細なステータスを取得します。

• パラメータ:

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

• 応答例:

  🖥️ Node: pve-compute-01
    • Status: ONLINE
    • Uptime: ⏳ 156d 12h
    • CPU Usage: 42.3%
    • CPU Cores: 64 (AMD EPYC 7763)
    • Memory: 186.5 GB / 512.0 GB (36.4%)
    • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
    • Temperature: 38°C

get_vms

クラスター全体のすべての VM を一覧表示します。

• パラメータ: なし

• 応答例:

  🗃️ Virtual Machines
  
  🗃️ prod-db-master (ID: 100)
    • Status: RUNNING
    • Node: pve-compute-01
    • CPU Cores: 16
    • Memory: 92.3 GB / 128.0 GB (72.1%)
  
  🗃️ prod-web-01 (ID: 102)
    • Status: RUNNING
    • Node: pve-compute-01
    • CPU Cores: 8
    • Memory: 12.8 GB / 32.0 GB (40.0%)

ストレージの取得

使用可能なストレージを一覧表示します。

• パラメータ: なし

• 応答例:

  💾 Storage Pools
  
  💾 ceph-prod
    • Status: ONLINE
    • Type: rbd
    • Usage: 12.8 TB / 20.0 TB (64.0%)
    • IOPS: ⬆️ 15.2k ⬇️ 12.8k
  
  💾 local-zfs
    • Status: ONLINE
    • Type: zfspool
    • Usage: 3.2 TB / 8.0 TB (40.0%)
    • IOPS: ⬆️ 42.8k ⬇️ 35.6k

クラスターステータスの取得

クラスター全体のステータスを取得します。

• パラメータ: なし

• 応答例:

  ⚙️ Proxmox Cluster
  
    • Name: enterprise-cloud
    • Status: HEALTHY
    • Quorum: OK
    • Nodes: 4 ONLINE
    • Version: 8.1.3
    • HA Status: ACTIVE
    • Resources:
      - Total CPU Cores: 192
      - Total Memory: 1536 GB
      - Total Storage: 70 TB
    • Workload:
      - Running VMs: 7
      - Total VMs: 8
      - Average CPU Usage: 38.6%
      - Average Memory Usage: 42.8%

VMコマンド実行

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

• パラメータ:

  • node (文字列、必須): VM が実行されているノードの名前

  • vmid (文字列、必須): VMのID

  • command (文字列、必須): 実行するコマンド

• 応答例:

  🔧 Console Command Result
    • Status: SUCCESS
    • Command: systemctl status nginx
    • Node: pve-compute-01
    • VM: prod-web-01 (ID: 102)
  
  Output:
  ● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago

• 要件：

  • VMが実行中である必要があります

  • QEMUゲストエージェントがVMにインストールされ、実行されている必要があります

  • ゲストエージェントでコマンド実行権限を有効にする必要があります

• エラー処理:

  • VMが実行していない場合はエラーを返します

  • VMが見つからない場合はエラーを返します

  • コマンド実行が失敗した場合はエラーを返します

  • コマンドがゼロ以外の終了コードを返した場合でもコマンド出力を含めます

👨‍💻 開発

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

• テストを実行する: pytest

• フォーマットコード: black .

• 型チェック: mypy .

• 糸くず： ruff .

📁 プロジェクト構造

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # Main MCP server implementation
│       ├── config/            # Configuration handling
│       ├── core/              # Core functionality
│       ├── formatting/        # Output formatting and themes
│       ├── tools/             # Tool implementations
│       │   └── console/       # VM console operations
│       └── utils/             # Utilities (auth, logging)
├── tests/                     # Test suite
├── proxmox-config/
│   └── config.example.json    # Configuration template
├── pyproject.toml            # Project metadata and dependencies
└── LICENSE                   # MIT License

📄 ライセンス

MITライセンス