MCP Proxmox

🚀 MCP Proxmox Server

MCP Proxmox Server 是一個用 Python 編寫的高級 Proxmox 模型上下文協議（MCP）服務器，它提供了豐富的 Proxmox 實用工具，可用於發現、生命週期管理、網絡配置、快照/備份、指標監控、資源池/權限管理以及編排等操作。

🚀 快速開始

克隆倉庫並創建虛擬環境

git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

# （可選）在本地安裝包
pip install -e .

配置 .env 文件

• 複製 .env.example 文件到 .env 並編輯相關值：

cp .env.example .env

.env 文件中的鍵值示例：

PROXMOX_API_URL="https://proxmox.example.com:8006"
PROXMOX_TOKEN_ID="root@pam!mcp-proxmox"
PROXMOX_TOKEN_SECRET="<secret>"
PROXMOX_VERIFY="true"
PROXMOX_DEFAULT_NODE="pve"
PROXMOX_DEFAULT_STORAGE="local-lvm"
PROXMOX_DEFAULT_BRIDGE="vmbr0"

⚠️ 重要提示

• 請使用具有適當訪問控制列表（ACL）的 API 令牌；對於發現操作，根目錄下的 PVEAuditor 權限已足夠；對於生命週期管理操作，請在資源池上授予更窄的角色（例如 PVEVMAdmin）。
• 使用 .env 文件可以避免 zsh 歷史擴展中因令牌 ID 包含 ! 而導致的問題。

運行 MCP 服務器（標準輸入輸出）

推薦方式（模塊形式）

source .venv/bin/activate
python -m proxmox_mcp.server

已安裝的控制檯腳本方式

source .venv/bin/activate
proxmox-mcp

在 Cursor 中配置

編輯 ~/.cursor/mcp.json 文件（可移植示例）：

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

在 Claude for Desktop 中配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

✨ 主要特性

核心發現工具

虛擬機生命週期管理工具

• proxmox-clone-vm：將模板虛擬機克隆到新的 VMID/名稱（支持目標節點、存儲）
• proxmox-create-vm：從 ISO/模板創建新的虛擬機（最小配置）
• proxmox-delete-vm：刪除虛擬機（需確認、可清除）
• proxmox-start-vm / proxmox-stop-vm / proxmox-reboot-vm / proxmox-shutdown-vm：管理虛擬機電源狀態（停止操作支持硬停止和超時設置）
• proxmox-migrate-vm：即時/離線遷移到其他節點
• proxmox-resize-vm-disk：擴展目標磁盤（如 scsi0）的大小（GB）
• proxmox-configure-vm：設置白名單參數（核心數、內存、氣球、網絡、代理等）

LXC 容器生命週期管理工具

• proxmox-create-lxc：從模板創建容器（CPU/內存、根文件系統大小、網絡、存儲）
• proxmox-delete-lxc / proxmox-start-lxc / proxmox-stop-lxc / proxmox-configure-lxc：管理容器生命週期和配置

雲初始化與網絡配置工具

• proxmox-cloudinit-set：設置雲初始化參數（ipconfig0、ssh 密鑰、ci 用戶/密碼）
• proxmox-vm-nic-add / proxmox-vm-nic-remove：添加/移除網卡（網橋、模型、VLAN）
• proxmox-vm-firewall-get / proxmox-vm-firewall-set：獲取/設置每個虛擬機的防火牆狀態和規則

鏡像、模板、快照、備份工具

• proxmox-upload-iso / proxmox-upload-template：將 ISO 或 LXC 模板上傳到存儲
• proxmox-template-vm：將虛擬機轉換為模板
• proxmox-list-snapshots / proxmox-create-snapshot / proxmox-delete-snapshot / proxmox-rollback-snapshot：管理快照；回滾操作支持 wait 參數
• proxmox-backup-vm / proxmox-restore-vm：運行 vzdump 備份和恢復存檔

指標監控工具

• proxmox-vm-metrics：獲取虛擬機的 RRD 指標（時間範圍、合併函數）
• proxmox-node-metrics：獲取節點的 RRD 指標

資源池、用戶、權限管理工具

• proxmox-list-pools / proxmox-create-pool / proxmox-delete-pool / proxmox-pool-add / proxmox-pool-remove
• proxmox-list-users / proxmox-list-roles / proxmox-assign-permission

編排輔助工具

• proxmox-wait-task：輪詢任務直到完成或超時
• proxmox-register-vm-as-host：為 Ansible 清單生成 JSON/INI 片段（主機名、IP、SSH 用戶/密鑰）
• proxmox-guest-exec（可選）：通過 QEMU 來賓代理運行命令（需要來賓中安裝代理）

💻 使用示例

基礎用法

• 列出節點：

{}

用於 proxmox-list-nodes 工具。

• 列出節點 pve 上的虛擬機：

{ "node": "pve" }

用於 proxmox-list-vms 工具。

高級用法

• 克隆模板虛擬機：

{ "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }

用於 proxmox-clone-vm 工具。

• 配置雲初始化 IP：

{ "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }

用於 proxmox-cloudinit-set 工具。

📚 詳細文檔

• 指南參考：MCP 快速入門（Python）
• 結構鏡像：bsahane/mcp-ansible

🔧 技術細節

• 服務器使用標準輸入輸出傳輸；僅將 MCP 協議打印到標準輸出。日誌記錄到標準錯誤輸出。
• 身份驗證使用環境變量和/或 .env 文件。
• 跨節點的名稱衝突會返回明確的錯誤，除非指定 node 參數。

📄 許可證

本項目採用 MIT 許可證。