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-list-nodes | 列出集群节点（包含名称、状态、CPU/RAM/磁盘摘要） | "List cluster nodes" | [ { "node": "pve", "status": "online", ... } ] | | proxmox-node-status | 详细的节点健康信息（负载、正常运行时间、版本） | { "node": "pve" } | { "kversion": "...", "uptime": 123456, ... } | | proxmox-list-vms | 列出虚拟机（可按节点、状态、名称子串过滤） | { "node": "pve", "status": "running" } | [ { "vmid": 100, "name": "web01", ... } ] | | proxmox-vm-info | 根据 vmid 或 name（可选节点）获取虚拟机详细信息，包括配置 | { "name": "web01" } | { "selector": {...}, "config": {...} } | | proxmox-list-lxc | 列出 LXC 容器（可过滤） | { "node": "pve" } | [ { "vmid": 50001, "name": "ct01", ... } ] | | proxmox-lxc-info | 根据 vmid 或 name（可选节点）获取 LXC 容器详细信息 | { "vmid": 50001 } | { "selector": {...}, "config": {...} } | | proxmox-list-storage | 列出存储（类型、可用/已用空间） | {} | [ { "storage": "local-lvm", "type": "lvmthin", ... } ] | | proxmox-storage-content | 列出存储内容（ISO、模板、镜像） | { "node": "pve", "storage": "local" } | [ { "volid": "local:iso/foo.iso", ... } ] | | proxmox-list-bridges | 列出节点网桥（vmbr...） | { "node": "pve" } | [ { "iface": "vmbr0", ... } ] | | proxmox-list-tasks | 最近的任务（可按节点、用户过滤） | { "node": "pve", "limit": 20 } | [ { "upid": "UPID:...", "status": "OK" }, ... ] | | proxmox-task-status | 检查任务状态 | { "upid": "UPID:..." } | { "status": "stopped", "exitstatus": "OK" } |

虚拟机生命周期管理工具

• 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 许可证。