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