Proxmoxmcp Plus

🚀 ProxmoxMCP-Plus - 增強版Proxmox MCP服務器

這是一個基於Python的增強型模型上下文協議（MCP）服務器，用於與Proxmox虛擬化平臺進行交互。本項目基於 canvrno/ProxmoxMCP 構建，新增了眾多功能並進行了改進，提供了完整的OpenAPI集成和更強大的虛擬化管理能力。

🚀 快速開始

本項目是一個增強版的Proxmox MCP服務器，旨在簡化和增強與Proxmox虛擬化平臺的交互。你可以通過以下步驟快速搭建並使用該服務器。

✨ 主要特性

與原版本相比的主要增強功能：

• ✨ 完整的虛擬機生命週期管理

  • 全新的 create_vm 工具 - 支持使用自定義配置創建虛擬機
  • 新的 delete_vm 工具 - 安全刪除虛擬機（支持強制刪除選項）
  • 增強的智能存儲類型檢測（LVM/基於文件）

• 🔧 擴展的電源管理功能

  • start_vm - 啟動虛擬機
  • stop_vm - 強制停止虛擬機
  • shutdown_vm - 正常關閉虛擬機
  • reset_vm - 重啟虛擬機

• 🐳 新增容器支持

  • get_containers - 列出所有LXC容器及其狀態

• 📊 增強的監控和顯示功能

  • 改進的存儲池狀態監控
  • 更詳細的集群健康狀態檢查
  • 豐富的輸出格式和主題

• 🌐 完整的OpenAPI集成

  • 11個完整的REST API端點
  • 可用於生產環境的Docker部署
  • 完美的Open WebUI集成
  • 支持自然語言創建虛擬機

• 🛡️ 生產級的安全性和穩定性

  • 增強的錯誤處理機制
  • 全面的參數驗證
  • 生產級日誌記錄
  • 完整的單元測試覆蓋

其他特性：

• 🤖 與Cline和Open WebUI完全集成
• 🛠️ 使用官方MCP SDK構建
• 🔒 與Proxmox進行基於安全令牌的身份驗證
• 🖥️ 完整的虛擬機生命週期管理（創建、啟動、停止、重置、關閉、刪除）
• 💻 執行虛擬機控制檯命令
• 🐳 支持LXC容器管理
• 🗃️ 智能存儲類型檢測（LVM/基於文件）
• 📝 可配置的日誌系統
• ✅ 使用Pydantic實現類型安全
• 🎨 豐富的輸出格式和可自定義主題
• 🌐 用於集成的OpenAPI REST端點
• 📡 11個功能齊全的API端點

📦 安裝指南

前提條件

• 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
   # 或者
   .\.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 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到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端點：

虛擬機管理工具

create_vm

使用指定的資源創建一個新的虛擬機。

參數：

• node（字符串，必需）：節點名稱
• vmid（字符串，必需）：新虛擬機的ID
• name（字符串，必需）：虛擬機名稱
• cpus（整數，必需）：CPU核心數（1 - 32）
• memory（整數，必需）：內存（MB）（512 - 131072）
• disk_size（整數，必需）：磁盤大小（GB）（5 - 1000）
• storage（字符串，可選）：存儲池名稱
• ostype（字符串，可選）：操作系統類型（默認：l26）

API端點：

POST /create_vm
Content-Type: application/json

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

示例響應：

🎉 虛擬機200創建成功！

📋 虛擬機配置：
  • 名稱：my-vm
  • 節點：pve
  • 虛擬機ID：200
  • CPU核心數：1
  • 內存：2048 MB（2.0 GB）
  • 磁盤：10 GB（local-lvm，原始格式）
  • 存儲類型：lvmthin
  • 網絡：virtio（橋接=vmbr0）
  • QEMU代理：已啟用

🔧 任務ID：UPID:pve:001AB729:0442E853:682FF380:qmcreate:200:root@pam!mcp

虛擬機電源管理 🆕

• 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）
  • 狀態：運行中
  • 節點：pve
  • CPU核心數：2
  • 內存：1.5 GB / 2.0 GB（75.0%）

監控工具

get_nodes

列出Proxmox集群中的所有節點。

API端點： POST /get_nodes

示例響應：

🖥️ Proxmox節點

🖥️ pve-compute-01
  • 狀態：在線
  • 正常運行時間：⏳ 156天12小時
  • CPU核心數：64
  • 內存：186.5 GB / 512.0 GB（36.4%）

get_node_status

獲取特定節點的詳細狀態。

參數：

• node（字符串，必需）：節點名稱

API端點： POST /get_node_status

get_vms

列出集群中的所有虛擬機。

API端點： POST /get_vms

get_storage

列出可用的存儲池。

API端點： POST /get_storage

get_cluster_status

獲取集群的整體狀態和健康狀況。

API端點： POST /get_cluster_status

execute_vm_command

使用QEMU Guest Agent在虛擬機的控制檯中執行命令。

參數：

• node（字符串，必需）：虛擬機運行所在的節點名稱
• vmid（字符串，必需）：虛擬機的ID
• command（字符串，必需）：要執行的命令

API端點： POST /execute_vm_command

要求：

• 虛擬機必須正在運行
• 虛擬機中必須安裝並運行QEMU Guest Agent

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"
}

自然語言創建虛擬機

用戶現在可以使用自然語言請求創建虛擬機：

• "能否創建一個具有1個CPU核心、2 GB內存和10 GB存儲磁盤的虛擬機"
• "創建一個用於測試的最小資源虛擬機"
• "我需要一個具有4個核心和8 GB內存的開發服務器"

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               # 虛擬機管理（創建/電源） 🆕
│       │   ├── container.py        # 容器管理 🆕
│       │   └── console/            # 虛擬機控制檯操作
│       └── utils/                   # 實用工具（身份驗證、日誌記錄）
│
├── 📁 tests/                       # 單元測試套件
├── 📁 test_scripts/                # 集成測試和演示
│   ├── README.md                   # 測試文檔
│   ├── test_vm_power.py           # 虛擬機電源管理測試 🆕
│   ├── test_vm_start.py           # 虛擬機啟動測試
│   ├── test_create_vm.py          # 虛擬機創建測試 🆕
│   └── 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       # 虛擬機創建指南
    ├── OPENAPI_DEPLOYMENT.md      # OpenAPI部署
    └── LICENSE                    # MIT許可證

測試

運行單元測試

pytest

運行集成測試

cd test_scripts

# 測試虛擬機電源管理
python test_vm_power.py

# 測試虛擬機創建
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 "{}"

# 測試虛擬機創建
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] 虛擬機創建（用戶需求：1個CPU + 2 GB內存 + 10 GB存儲） 🆕
• [x] 虛擬機電源管理（啟動VPN服務器ID:101） 🆕
• [x] 虛擬機刪除功能 🆕
• [x] 容器管理（LXC） 🆕
• [x] 存儲兼容性（LVM/基於文件）
• [x] OpenAPI集成（端口8811）
• [x] Open WebUI集成
• [x] 錯誤處理和驗證
• [x] 完整的文檔和測試

可用於生產環境！

ProxmoxMCP Plus現在已完全可以用於生產環境！

當用戶說 "能否創建一個具有1個CPU核心、2 GB內存和10 GB存儲磁盤的虛擬機" 時，AI助手可以：

1. 📞 調用 create_vm API
2. 🔧 自動選擇合適的存儲和格式
3. 🎯 創建符合要求的虛擬機
4. 📊 返回詳細的配置信息
5. 💡 提供下一步建議

開發

激活虛擬環境後：

• 運行測試：pytest
• 格式化代碼：black .
• 類型檢查：mypy .
• 代碼檢查：ruff .

📄 許可證

本項目採用MIT許可證。

特別感謝

• 感謝 @canvrno 提供了優秀的基礎項目 ProxmoxMCP
• 感謝Proxmox社區提供了強大的虛擬化平臺
• 感謝所有貢獻者和用戶的支持

---

準備好部署了！ 🎉 你擁有OpenAPI集成的增強版Proxmox MCP服務已可用於生產環境。