shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

cursor-proxmox-mcp

Cursor专用的Proxmox虚拟化管理MCP服务，提供完整的虚拟机生命周期管理、容器支持和OpenAPI集成

article

README

🚀 cursor-proxmox-mcp - 支持OpenAPI（可选）的Cursor Proxmox MCP服务器

cursor-proxmox-mcp是一个专注于Cursor的基于Python的模型上下文协议（MCP）服务器，用于与Proxmox虚拟化平台进行交互，并进行了修复和增强。

cursor-proxmox-mcp 截图

🚀 快速开始

构建工具

安装步骤

前提条件

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

在开始之前，请确保您拥有：

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

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

  1. 克隆并设置环境：
# 克隆仓库
git clone https://github.com/agentify-sh/cursor-proxmox-mcp.git
cd ProxmoxMCP-Plus

# 创建并激活虚拟环境
uv venv

# 或者强制使用3.11（用于mcpo依赖）
python3.11 -m venv .venv

# 然后激活它
source .venv/bin/activate  # Linux/macOS
# 或者
.\.venv\Scripts\Activate.ps1  # Windows
  1. 安装依赖项：
# 安装开发依赖项
uv pip install -e ".[dev]"

# 或者通过pip安装
pip install -e .
pip install pytest pytest-asyncio black mypy ruff types-requests
pip install mcpo # 需要python 3.11
  1. 创建配置：
# 创建配置目录并复制模板
mkdir -p proxmox-config
cp proxmox-config/config.example.json proxmox-config/config.json
  1. 编辑 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"      # 可选：记录到文件
    }
}

验证安装

  1. 检查Python环境：
python -c "import proxmox_mcp; print('Installation OK')"
  1. 运行测试：
pytest
  1. 验证配置：
# 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

运行服务器

开发模式

用于测试和开发：

# 首先激活虚拟环境
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": []
        }
    }
}

✨ 主要特性

🆕 新特性和改进

所有测试通过

  • 之前测试无法完成，现已修复。

持续支持

  • 由于我需要使用该工具管理自己的Proxmox实例，因此我将继续根据需要发布更新和更改。

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

  • ✨ 完整的VM生命周期管理

    • 全新的 create_vm 工具 - 支持使用自定义配置创建虚拟机
    • 新的 delete_vm 工具 - 安全删除VM（带有强制删除选项）
    • 增强的智能存储类型检测（LVM/基于文件）

  • 🔧 扩展的电源管理功能

    • start_vm - 启动虚拟机
    • stop_vm - 强制停止虚拟机
    • shutdown_vm - 正常关闭虚拟机
    • reset_vm - 重启虚拟机

  • 🐳 新的容器支持

    • get_containers - 列出所有LXC容器及其状态

  • 📊 增强的监控和显示

    • 改进的存储池状态监控
    • 更详细的集群健康状态检查
    • 丰富的输出格式和主题

  • 🌐 完整的OpenAPI集成

    • 11个完整的REST API端点
    • 生产就绪的Docker部署
    • 完美的Open WebUI集成
    • 支持自然语言创建VM

  • 🛡️ 生产级的安全性和稳定性

    • 增强的错误处理机制
    • 全面的参数验证
    • 生产级日志记录
    • 完整的单元测试覆盖

其他特性

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

💻 使用示例

可用工具和API端点

服务器提供11个全面的MCP工具和相应的REST API端点：

VM管理工具

create_vm

创建具有指定资源的新虚拟机。

参数：

  • node（字符串，必需）：节点名称
  • vmid（字符串，必需）：新VM的ID
  • name（字符串，必需）：VM的名称
  • 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创建成功！

📋 VM配置：
  • 名称: my-vm
  • 节点: pve
  • VM ID: 200
  • CPU核心数: 1
  • 内存: 2048 MB (2.0 GB)
  • 磁盘: 10 GB (local-lvm, raw格式)
  • 存储类型: lvmthin
  • 网络: virtio (bridge=vmbr0)
  • QEMU代理: 已启用

🔧 任务ID: UPID:pve:001AB729:0442E853:682FF380:qmcreate:200:root@pam!mcp
VM电源管理 🆕
  • 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
  • 正常运行时间: ⏳ 156d 12h
  • CPU核心数: 64
  • 内存: 186.5 GB / 512.0 GB (36.4%)
  • get_node_status：获取特定节点的详细状态。 参数：
  • node（字符串，必需）：节点名称 API端点： POST /get_node_status
  • get_vms：列出集群中的所有VM。 API端点： POST /get_vms
  • get_storage：列出可用的存储池。 API端点： POST /get_storage
  • get_cluster_status：获取集群的整体状态和健康状况。 API端点： POST /get_cluster_status
  • execute_vm_command：使用QEMU Guest Agent在VM控制台中执行命令。 参数：
  • node（字符串，必需）：VM运行的节点名称
  • vmid（字符串，必需）：VM的ID
  • command（字符串，必需）：要执行的命令 API端点： POST /execute_vm_command 要求：
  • VM必须正在运行
  • VM中必须安装并运行QEMU Guest Agent

Open WebUI集成

配置Open WebUI

  1. 访问您的Open WebUI实例
  2. 导航到 设置 → 连接 → OpenAPI
  3. 添加新的API配置：
{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "增强的Proxmox虚拟化管理API"
}

自然语言创建VM

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

  • "能否创建一个具有1个CPU核心、2GB内存和10GB存储磁盘的VM"
  • "创建一个用于测试的最小资源的新VM"
  • "我需要一个具有4个核心和8GB RAM的开发服务器"

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

存储类型支持

智能存储检测

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

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

📚 详细文档

Proxmox API令牌设置

  1. 登录到您的Proxmox Web界面
  2. 导航到数据中心 -> 权限 -> API令牌
  3. 创建一个新的API令牌：
  • 选择一个用户（例如，root@pam）
  • 输入令牌ID（例如，"mcp-token"）
  • 如果您需要完全访问权限，请取消选中“权限分离”
  • 保存并复制令牌ID和密钥

项目结构

ProxmoxMCP-Plus/
├── 📁 src/                          # 源代码
│   └── proxmox_mcp/
│       ├── server.py                # 主要的MCP服务器实现
│       ├── config/                  # 配置处理
│       ├── core/                    # 核心功能
│       ├── formatting/              # 输出格式和主题
│       ├── tools/                   # 工具实现
│       │   ├── vm.py               # VM管理（创建/电源） 🆕
│       │   ├── container.py        # 容器管理 🆕
│       │   └── console/            # VM控制台操作
│       └── utils/                   # 实用工具（认证、日志记录）
│
├── 📁 tests/                       # 单元测试套件
├── 📁 test_scripts/                # 集成测试和演示
│   ├── README.md                   # 测试文档
│   ├── test_vm_power.py           # VM电源管理测试 🆕
│   ├── test_vm_start.py           # VM启动测试
│   ├── test_create_vm.py          # VM创建测试 🆕
│   └── 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       # VM创建指南
    ├── OPENAPI_DEPLOYMENT.md      # OpenAPI部署文档
    └── LICENSE                    # MIT许可证

测试

运行单元测试

pytest

运行集成测试

cd test_scripts

# 测试VM电源管理
python test_vm_power.py

# 测试VM启动
python test_vm_start.py

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

# 测试VM创建
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;
    }
}

故障排除

常见问题

  1. 端口已被使用
netstat -tlnp | grep 8811
# 如果需要，更改端口
mcpo --port 8812 -- ./start_server.sh
  1. 配置错误
# 验证配置文件
cat proxmox-config/config.json
  1. 连接问题
# 测试Proxmox连接性
curl -k https://your-proxmox:8006/api2/json/version

查看日志

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

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

部署状态

✅ 功能完成度：100%

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

生产就绪！

ProxmoxMCP Plus现在已完全准备好用于生产环境！

当用户说 "能否创建一个具有1个CPU核心、2GB内存和10GB存储磁盘的VM" 时，AI助手可以：

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

开发

激活虚拟环境后：

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

📄 许可证

本项目采用MIT许可证。

致谢

本项目基于优秀的开源项目 ProxmoxMCP 构建，感谢原作者 @RekklesNA 提供的基础框架和创意灵感！我将继续针对Cursor IDE进行更新。

特别感谢

  • 感谢 @RekklesNA 的改进
  • 感谢 @canvrno 提供的优秀基础项目 ProxmoxMCP
  • 感谢Proxmox社区提供的强大虚拟化平台
  • 感谢所有贡献者和用户的支持

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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端