🚀 Proxmox マネージャー - Proxmox MCP サーバー
Proxmox ハイパーバイザーと対話するための Python ベースの Model Context Protocol (MCP) サーバー。ノード、VM、コンテナを管理するためのクリーンなインターフェースを提供します。
🏗️ で構築
✨ 特徴
- 🤖 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: クイックインストール (推奨)
- 環境のクローンとセットアップ:
# 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
- 依存関係をインストールします:
# Install with development dependencies
uv pip install -e ".[dev]"
- 構成を作成します。
# Create config directory and copy template
mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json
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
}
}
インストールの確認
- Python 環境を確認します。
python -c "import proxmox_mcp; print('Installation OK')"
- テストを実行します。
- 構成を確認します。
# 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トークンの設定
- Proxmoxウェブインターフェースにログインする
- データセンター -> 権限 -> APIトークンに移動します
- 新しい 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: 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のIDcommand (文字列、必須): 実行するコマンド
- 応答例:
🔧 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ライセンス