Cursor Proxmox MCP

🚀 cursor-proxmox-mcp - 支持OpenAPI（可選）的Cursor Proxmox MCP服務器

cursor-proxmox-mcp是一個專注於Cursor的基於Python的模型上下文協議（MCP）服務器，用於與Proxmox虛擬化平臺進行交互，並進行了修復和增強。

🚀 快速開始

構建工具

• Cursor
• Proxmoxer - Proxmox API的Python包裝器
• MCP SDK - 模型上下文協議SDK
• Pydantic - 使用Python類型註解進行數據驗證

安裝步驟

前提條件

• 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

運行服務器

開發模式

用於測試和開發：

# 首先激活虛擬環境
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": []
        }
    }
}

✨ 主要特性

🆕 新特性和改進

所有測試通過

• 之前測試無法完成，現已修復。

持續支持

• 由於我需要使用該工具管理自己的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和Open WebUI完全集成
• 🛠️ 使用官方MCP SDK構建
• 🔒 使用基於令牌的安全認證與Proxmox通信
• 🖥️ 完整的VM生命週期管理（創建、啟動、停止、重置、關閉、刪除）
• 💻 執行VM控制檯命令
• 🐳 支持LXC容器管理
• 🗃️ 智能存儲類型檢測（LVM/基於文件）
• 📝 可配置的日誌系統
• ✅ 使用Pydantic實現類型安全
• 🎨 豐富的輸出格式和可定製主題
• 🌐 用於集成的OpenAPI REST端點
• 📡 11個功能齊全的API端點

💻 使用示例

可用工具和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（字符串，可選）：操作系統類型（默認：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 Guest Agent在VM控制檯中執行命令。 參數：
• node（字符串，必需）：VM運行的節點名稱
• vmid（字符串，必需）：VM的ID
• command（字符串，必需）：要執行的命令 API端點： POST /execute_vm_command 要求：
• VM必須正在運行
• VM中必須安裝並運行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"
}

自然語言創建VM

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

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

AI助手將自動調用相應的API並提供詳細反饋。

存儲類型支持

智能存儲檢測

ProxmoxMCP Plus自動檢測存儲類型並選擇合適的磁盤格式：

• LVM存儲（local-lvm, vm-storage）
  • ✅ 格式: raw
  • ✅ 高性能
  • ⚠️ 不支持雲初始化鏡像
• 基於文件的存儲（local, NFS, CIFS）
  • ✅ 格式: qcow2
  • ✅ 支持雲初始化
  • ✅ 靈活的快照功能

📚 詳細文檔

Proxmox API令牌設置

1. 登錄到您的Proxmox Web界面
2. 導航到數據中心 -> 權限 -> API令牌
3. 創建一個新的API令牌：

• 選擇一個用戶（例如，root@pam）
• 輸入令牌ID（例如，"mcp-token"）
• 如果您需要完全訪問權限，請取消選中“權限分離”
• 保存並複製令牌ID和密鑰

項目結構

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                # 服務器配置
│
├── 📄 Configuration Files
│   ├── pyproject.toml             # 項目元數據
│   ├── docker-compose.yml         # Docker編排
│   ├── Dockerfile                 # Docker鏡像定義
│   └── requirements.in            # 依賴項
│
├── 📄 Scripts
│   ├── start_server.sh            # MCP服務器啟動腳本
│   └── start_openapi.sh           # OpenAPI服務啟動腳本
│
└── 📄 Documentation
    ├── 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_vm_start.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內存和10GB存儲磁盤的VM" 時，AI助手可以：

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

開發

激活虛擬環境後：

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

📄 許可證

本項目採用MIT許可證。

致謝

本項目基於優秀的開源項目 ProxmoxMCP 構建，感謝原作者 @RekklesNA 提供的基礎框架和創意靈感！我將繼續針對Cursor IDE進行更新。

特別感謝

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

---

準備好部署了！ 🎉 您的支持OpenAPI集成的增強型Proxmox MCP服務已準備好用於生產環境。