ProxmoxMCP Plus

开发 Python

🚀 ProxmoxMCP-Plus - 增强版Proxmox MCP服务器

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

🚀 快速开始

本项目是一个增强型的Proxmox MCP服务器，为Proxmox虚拟化平台提供了更强大的管理功能。以下将详细介绍如何安装、配置和运行该项目。

✨ 主要特性

与原版本相比的重大改进：

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

其他特性：

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

📦 安装指南

前提条件

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

在开始之前，请确保您具备以下条件：

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

选项1：快速安装（推荐）

克隆并设置环境：

# 克隆仓库
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('Installation OK')"

运行测试：

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

💻 使用示例

基础用法

以下是使用 create_vm 工具创建虚拟机的示例：

POST /create_vm
Content-Type: application/json

{
"node": "pve",
"vmid": "200",
"name": "my-vm",
"cpus": 1,
"memory": 2048,
"disk_size": 10
}

高级用法

以下是使用自然语言创建虚拟机的示例：用户可以使用自然语言请求创建虚拟机，例如：

"Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk"
"Create a new VM for testing with minimal resources"
"I need a development server with 4 cores and 8GB RAM"

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

📚 详细文档

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端点，以便与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": []
}
}
}

可用工具和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
}

示例响应：

🎉 VM 200 created successfully!

📋 VM Configuration:
• Name: my-vm
• Node: pve
• VM ID: 200
• CPU Cores: 1
• Memory: 2048 MB (2.0 GB)
• Disk: 10 GB (local-lvm, raw format)
• Storage Type: lvmthin
• Network: virtio (bridge=vmbr0)
• QEMU Agent: Enabled

🔧 Task 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

示例响应：

🐳 Containers

🐳 nginx-server (ID: 200)
• Status: RUNNING
• Node: pve
• CPU Cores: 2
• Memory: 1.5 GB / 2.0 GB (75.0%)

监控工具

get_nodes：列出Proxmox集群中的所有节点。 API端点： POST /get_nodes

示例响应：

🖥️ Proxmox Nodes

🖥️ pve-compute-01
• Status: ONLINE
• Uptime: ⏳ 156d 12h
• CPU Cores: 64
• Memory: 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": "Enhanced Proxmox Virtualization Management API"
}

自然语言创建虚拟机

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

"Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk"
"Create a new VM for testing with minimal resources"
"I need a development server with 4 cores and 8GB RAM"

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

存储类型支持

智能存储检测

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

LVM存储（local-lvm, vm-storage）
- ✅ 格式：raw
- ✅ 高性能
- ⚠️ 不支持云初始化镜像
基于文件的存储（local, NFS, CIFS）
- ✅ 格式：qcow2
- ✅ 支持云初始化
- ✅ 灵活的快照功能

项目结构

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                # 服务器配置
│
├── 📄 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       # 虚拟机创建指南
├── OPENAPI_DEPLOYMENT.md      # OpenAPI部署
└── LICENSE                    # MIT许可证

测试

运行单元测试

pytest

运行集成测试

cd test_scripts

# 测试虚拟机电源管理
python test_vm_power.py

# 测试虚拟机创建
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 "{}"

# 测试虚拟机创建
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;
}
}

故障排除

常见问题

端口已被使用

netstat -tlnp | grep 8811
# 如有需要，更改端口
mcpo --port 8812 -- ./start_server.sh

配置错误

# 验证配置文件
cat proxmox-config/config.json

连接问题

# 测试Proxmox连接性
curl -k https://your-proxmox:8006/api2/json/version

查看日志

# 查看服务日志
tail -f proxmox_mcp.log

# Docker日志
docker logs proxmox-mcp-api -f

部署状态

✅ 功能完成度：100%

[x] 虚拟机创建（用户需求：1个CPU核心 + 2GB内存 + 10GB存储） 🆕
[x] 虚拟机电源管理（启动VPN服务器ID:101） 🆕
[x] 虚拟机删除功能 🆕
[x] 容器管理（LXC） 🆕
[x] 存储兼容性（LVM/基于文件）
[x] OpenAPI集成（端口8811）
[x] Open WebUI集成
[x] 错误处理和验证
[x] 完整的文档和测试

已准备好投入生产！

ProxmoxMCP Plus现在已完全可以用于生产环境！

当用户说 "Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk" 时，AI助手可以：

📞 调用 create_vm API
🔧 自动选择合适的存储和格式
🎯 创建符合要求的虚拟机
📊 返回详细的配置信息
💡 提供下一步的建议

开发

激活虚拟环境后：

运行测试：pytest
格式化代码：black .
类型检查：mypy .
代码检查：ruff .

📄 许可证

本项目采用MIT许可证。

致谢

本项目基于优秀的开源项目 ProxmoxMCP 构建，感谢 @canvrno 提供的基础框架和创意灵感！同时，感谢Proxmox社区提供的强大虚拟化平台，以及所有贡献者和用户的支持。

准备好部署了！ 🎉 您的增强型Proxmox MCP服务已集成OpenAPI，可用于生产环境。

0 条评论
分类：开发

ProxmoxMCP Plus

🚀 ProxmoxMCP-Plus - 增强版Proxmox MCP服务器

🚀 快速开始

✨ 主要特性

与原版本相比的重大改进：

其他特性：

📦 安装指南

前提条件

选项1：快速安装（推荐）

验证安装

💻 使用示例

基础用法

高级用法

📚 详细文档

Proxmox API令牌设置

运行服务器

开发模式

OpenAPI部署（适用于生产环境）

快速启动OpenAPI服务

Docker部署

访问OpenAPI服务

Cline桌面集成

可用工具和API端点

虚拟机管理工具

create_vm

虚拟机电源管理 🆕

🆕 容器管理工具

get_containers 🆕

监控工具

Open WebUI集成

配置Open WebUI

自然语言创建虚拟机

存储类型支持

智能存储检测

项目结构

测试

运行单元测试

运行集成测试

使用curl进行API测试

生产环境安全

API密钥认证

Nginx反向代理

故障排除

常见问题

查看日志

部署状态

✅ 功能完成度：100%

已准备好投入生产！

开发

📄 许可证

致谢

0 个评论

相似服务问题

相关AI产品

热议话题 »