普罗克希姆MCP-增强版

Name: 普罗克希姆MCP-增强版
Author: RekklesNA

作者：RekklesNA26 星标更新：2025-09-15

安装使用来源：spider==github.com

项目介绍

ProxmoxMCP-Plus - 增强型Proxmox MCP服务器

基于Python的模型上下文协议（MCP）服务器，用于与Proxmox虚拟化平台交互。该项目基于**canvrno/ProxmoxMCP**，增加了许多新功能和改进，提供完整的OpenAPI集成和更强大的虚拟化管理能力。

致谢

本项目基于@canvrno的优秀开源项目ProxmoxMCP。感谢原作者提供的基础框架和创意灵感！

🆕 新功能和改进

相比原始版本的主要增强：

✨ 完整的虚拟机生命周期管理
- 全新的create_vm工具 - 支持创建具有自定义配置的虚拟机
- 新的delete_vm工具 - 安全删除虚拟机（带强制删除选项）
- 增强的智能存储类型检测（LVM/文件系统）
🔧 扩展的电源管理功能
- start_vm - 启动虚拟机
- stop_vm - 强制停止虚拟机
- shutdown_vm - 平稳关机
- reset_vm - 重启虚拟机
🐳 新的容器支持
- get_containers - 列出所有LXC容器及其状态
- start_container - 启动LXC容器
- stop_container - 停止LXC容器
- restart_container - 重启LXC容器（强制/平稳）
- update_container_resources - 调整容器CPU、内存、交换空间或扩展磁盘
📊 增强的监控和显示
- 改进的存储池状态监控
- 更详细的集群健康状况检查
- 丰富的输出格式化和主题
🌐 完整的OpenAPI集成
- 11个完整的REST API端点
- 生产级Docker部署
- 完美的Open WebUI集成
- 自然语言虚拟机创建支持
🛡️ 生产级安全性和稳定性
- 增强的错误处理机制
- 全面的参数验证
- 生产级别的日志记录
- 完整的单元测试覆盖

构建于

Cline - 自主编码代理 - 使用Cline更快地工作
Proxmoxer - Proxmox API的Python封装
MCP SDK - 模型上下文协议SDK
Pydantic - 使用Python类型注解进行数据验证

功能

🤖 完整集成Cline和Open WebUI
🛠️ 使用官方MCP SDK构建
🔒 与Proxmox的安全令牌认证
🖥️ 完整的虚拟机生命周期管理（创建、启动、停止、重置、关机、删除）
💻 虚拟机控制台命令执行
🐳 LXC容器管理支持
🗃️ 智能存储类型检测（LVM/文件系统）
📝 可配置的日志系统
✅ 使用Pydantic实现类型安全
🎨 丰富的输出格式化和可定制的主题
🌐 集成用的OpenAPI REST端点
📡 11个完全可用的API端点

安装

预备条件

UV包管理器（推荐）
Python 3.9或更高版本
Git
访问带有API令牌凭证的Proxmox服务器

开始前，请确保您有：

Proxmox服务器主机名或IP地址
Proxmox API令牌（参见API令牌设置）
已安装UV (pip install uv)

快速安装（推荐）

克隆并设置环境：

# 克隆仓库
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

安装依赖项：

# 安装开发依赖项
uv pip install -e ".[dev]"

创建配置：

# 创建配置目录并复制模板
mkdir -p proxmox-config
cp proxmox-config/config.example.json proxmox-config/config.json

编辑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"      // 可选：记录到文件
    }
}

验证安装

检查Python环境：

python -c "import proxmox_mcp; print('安装成功')"

运行测试：
```
pytest
```

验证配置：

# 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令牌设置

登录到您的Proxmox Web界面
导航至数据中心 -> 权限 -> API令牌
创建一个新的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端点部署，以便与其他应用程序集成。

快速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": "/绝对路径/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/绝对路径/to/ProxmoxMCP-Plus",
            "env": {
                "PYTHONPATH": "/绝对路径/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/绝对路径/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)
  • 状态：RUNNING
  • 节点：pve
  • CPU核心数：2
  • 内存：1.5 GB / 2.0 GB (75.0%)

监控工具

get_nodes

列出Proxmox集群中的所有节点。

API端点： POST /get_nodes

示例响应：

🖥️ Proxmox节点

🖥️ pve-compute-01
  • 状态：ONLINE
  • 运行时间：⏳ 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

访问您的Open WebUI实例
导航至设置 → 连接 → OpenAPI
添加新的API配置：

{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "增强的Proxmox虚拟化管理API"
}

自然语言虚拟机创建

用户现在可以使用自然语言请求虚拟机：

"你能创建一个具有1个CPU核心和2GB内存以及10GB存储磁盘的虚拟机吗？"
"创建一个用于测试的具有最小资源的新虚拟机"
"我需要一个具有4个核心和8GB内存的开发服务器"

AI助手将自动调用相应的API并提供详细的反馈。

存储类型支持

智能存储检测

ProxmoxMCP Plus会自动检测存储类型并选择适当的磁盘格式：

LVM存储（local-lvm，vm-storage）

✅ 格式：raw
✅ 高性能
⚠️ 不支持cloud-init镜像

文件系统存储（local，NFS，CIFS）

✅ 格式：qcow2
✅ 支持cloud-init
✅ 灵活的快照能力

项目结构

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编排
│