AI导哈

Proxmox虚拟化管理服务器

一个基于TypeScript的Proxmox虚拟环境全面管理服务器，提供34种工具覆盖监控、生命周期管理、备份、克隆、资源管理等功能。

  • by scogonw
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 scogonw/mcp-proxmox

使用说明

🚀 Proxmox MCP服务器

一个生产就绪的、基于TypeScript的模型上下文协议（MCP）服务器，用于全面的Proxmox虚拟环境管理。采用最新的MCP SDK和规范标准构建。

现在有34个全面的工具，涵盖了完整的Proxmox管理生命周期！

📊 进化时间表

版本 工具 主要功能
v1.0 7 基本监控（JavaScript）
v2.0 7 用MCP 1.21.0重写TypeScript
v2.1 20 虚拟机生命周期、快照、任务监控
v2.2 34 备份、克隆、资源、迁移、防火墙

🏗️ 建筑

src/
├── index.ts              # Entry point with graceful shutdown
├── server.ts             # MCP server implementation (34 tools)
├── config.ts             # Configuration with validation
├── logger.ts             # Winston logging system
├── errors.ts             # Custom error classes
├── types.ts              # TypeScript type definitions
├── validation.ts         # Zod validation schemas (34 schemas)
├── formatters.ts         # Output formatting utilities
├── proxmox-client.ts     # API client with retry/rate limiting
└── tools/                # Individual tool implementations
    ├── nodes.ts          # Node management (2 tools)
    ├── vms.ts            # VM/container monitoring (3 tools)
    ├── storage.ts        # Storage management (1 tool)
    ├── cluster.ts        # Cluster health (1 tool)
    ├── lifecycle.ts      # VM power states (7 tools)
    ├── snapshots.ts      # Snapshot management (5 tools)
    ├── tasks.ts          # Task monitoring (4 tools)
    ├── backup.ts         # Backup operations (4 tools)
    ├── cloning.ts        # VM cloning & templates (2 tools)
    ├── resources.ts      # Resource management (3 tools)
    ├── migration.ts      # VM migration (2 tools)
    └── firewall.ts       # Firewall rules (4 tools)

🔥 完整功能集

📊 监控和状态（7个工具）

  • proxmox_get_nodes -列出所有具有状态的群集节点
  • proxmox_get_node_status -详细的节点度量（提升）
  • proxmox_get_vms -列出所有虚拟机和容器
  • proxmox_get_vm_status -详细的VM状态和指标
  • proxmox_execute_vm_command -在VM上执行命令（提升）
  • proxmox_get_storage -存储池和使用情况
  • proxmox_get_cluster_status -群集运行状况概述

⚡ VM生命周期（7个工具）

  • proxmox_vm_start -启动虚拟机和容器
  • proxmox_vm_stop -强制停止（硬关机）
  • proxmox_vm_shutdown -优雅的ACPI关闭
  • proxmox_vm_reboot -重新启动来宾操作系统
  • proxmox_vm_suspend -挂起到磁盘（仅限QEMU）
  • proxmox_vm_resume -停职简历
  • proxmox_vm_reset -硬复位（如复位按钮）

📸 快照（5个工具）

  • proxmox_snapshot_create -创建具有可选RAM状态的VM快照
  • proxmox_snapshot_list -列出VM的所有快照
  • proxmox_snapshot_rollback -回滚到快照
  • proxmox_snapshot_delete -删除快照
  • proxmox_snapshot_config -获取快照配置

📋 任务管理（4个工具）

  • proxmox_task_list -列出带有筛选功能的任务
  • proxmox_task_status -获取任务状态和进度
  • proxmox_task_log -检索任务日志
  • proxmox_task_stop -停止运行任务

💾 备份操作（4个工具）

  • proxmox_backup_create -使用快照/挂起/停止模式创建备份
  • proxmox_backup_list -列出存储上的备份
  • proxmox_backup_restore -从备份中还原虚拟机
  • proxmox_backup_delete -删除备份档案

🔄 克隆和模板（2个工具）

  • proxmox_vm_clone -克隆虚拟机（完整/链接、跨节点）
  • proxmox_vm_template -将虚拟机转换为模板

⚙️ 资源管理（3个工具）

  • proxmox_vm_config_get -获取完整的VM配置
  • proxmox_vm_config_update -更新VM参数（CPU、内存等）
  • proxmox_disk_resize -调整VM磁盘大小（仅限增长）

🔄 迁移（2个工具）

  • proxmox_vm_migrate_check -检查迁移兼容性
  • proxmox_vm_migrate -迁移虚拟机（在线/离线、本地磁盘）

🛡️ 防火墙（4个工具）

  • proxmox_firewall_rules_list -列出所有防火墙规则
  • proxmox_firewall_rule_create -创建防火墙规则
  • proxmox_firewall_rule_delete -删除防火墙规则
  • proxmox_firewall_options -获取防火墙配置

📦 安装

🐳 Docker安装（推荐）

运行Proxmox MCP Server最简单的方法是使用Docker。此方法适用于所有平台，并与Claude Desktop无缝集成。

Docker快速入门

# Clone repository
git clone https://github.com/gilby125/mcp-proxmox.git
cd mcp-proxmox

# Create and configure environment
cp .env.example .env
nano .env  # Add your Proxmox credentials

# Build and start
./docker-run.sh build
./docker-run.sh start

# Test
./docker-run.sh test

Claude桌面集成

添加到Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "proxmox-mcp-server",
        "node",
        "dist/index.js"
      ]
    }
  }
}

📖 完整的Docker指南：参见 医生.md 有关详细说明、故障排除和高级配置。

💻 本地安装（替代）

如果你想在没有Docker的情况下运行：

先决条件

  • Node.js 18+和npm
  • TypeScript知识（用于开发）
  • 具有API访问权限的Proxmox VE 7.0+
  • 具有适当权限的API令牌

快速安装

# Clone repository
git clone https://github.com/gilby125/mcp-proxmox.git
cd mcp-proxmox

# Install dependencies
npm install

# Build TypeScript
npm run build

# Copy environment template
cp .env.example .env

# Edit .env with your Proxmox credentials
nano .env

配置

创建 .env 文件：

# Required
PROXMOX_HOST=192.168.1.100
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-token-value-here

# Optional
PROXMOX_PORT=8006                    # Default: 8006
PROXMOX_ALLOW_ELEVATED=false        # Enable advanced features
PROXMOX_TIMEOUT=30000               # API timeout (ms)
PROXMOX_RETRY_ATTEMPTS=3            # Number of retries
PROXMOX_RETRY_DELAY=1000            # Base retry delay (ms)
LOG_LEVEL=info                      # debug, info, warn, error

🚀 用法

构建并运行

# Production build
npm run build
npm start

# Development mode (auto-rebuild)
npm run dev

# Type checking only
npm run typecheck

# Clean and rebuild
npm run rebuild

测试MCP服务器

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

# Get cluster nodes
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "proxmox_get_nodes", "arguments": {}}}' | npm start

# Create a snapshot
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "proxmox_snapshot_create", "arguments": {"node": "pve1", "vmid": 100, "snapname": "backup-2025"}}}' | npm start

MCP客户端配置

对于Claude Code或其他MCP客户：

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/mcp-proxmox"
    }
  }
}

🛠️ 工具示例

VM生命周期管理

// Start a VM
proxmox_vm_start({
  node: "pve1",
  vmid: 100,
  type: "qemu"
})

// Graceful shutdown with timeout
proxmox_vm_shutdown({
  node: "pve1",
  vmid: 100,
  timeout: 300
})

快照操作

// Create snapshot with RAM state
proxmox_snapshot_create({
  node: "pve1",
  vmid: 100,
  snapname: "before-upgrade",
  description: "Snapshot before system upgrade",
  vmstate: true  // Include RAM for running snapshots
})

// Rollback to snapshot
proxmox_snapshot_rollback({
  node: "pve1",
  vmid: 100,
  snapname: "before-upgrade"
})

备份和恢复

// Create backup with snapshot mode
proxmox_backup_create({
  node: "pve1",
  vmid: 100,
  storage: "backup-storage",
  mode: "snapshot",      // Live backup
  compress: "zstd"       // Best compression
})

// List backups
proxmox_backup_list({
  node: "pve1",
  storage: "backup-storage",
  vmid: 100  // Optional filter
})

// Restore backup
proxmox_backup_restore({
  node: "pve1",
  storage: "backup-storage",
  archive: "vzdump-qemu-100-2025_11_06-14_30_00.vma.zst",
  vmid: 101,  // Restore to new ID
  force: false
})

克隆和模板

// Create full clone
proxmox_vm_clone({
  node: "pve1",
  vmid: 100,
  newid: 200,
  name: "web-server-02",
  full: true,           // Full clone (independent)
  target: "pve2"        // Clone to different node
})

// Convert to template
proxmox_vm_template({
  node: "pve1",
  vmid: 100
})

资源管理

// Update VM configuration
proxmox_vm_config_update({
  node: "pve1",
  vmid: 100,
  config: {
    cores: 4,
    memory: 8192,
    balloon: 4096
  }
})

// Resize disk
proxmox_disk_resize({
  node: "pve1",
  vmid: 100,
  disk: "scsi0",
  size: "+50G"  // Grow by 50GB
})

迁移

// Check migration compatibility
proxmox_vm_migrate_check({
  node: "pve1",
  vmid: 100,
  target: "pve2"
})

// Perform live migration
proxmox_vm_migrate({
  node: "pve1",
  vmid: 100,
  target: "pve2",
  online: true,           // Live migration
  withLocalDisks: true    // Migrate local disks
})

防火墙管理

// Create firewall rule
proxmox_firewall_rule_create({
  node: "pve1",
  vmid: 100,
  action: "ACCEPT",
  ruleType: "in",
  enable: true,
  proto: "tcp",
  dport: "80,443",
  source: "0.0.0.0/0",
  comment: "Allow HTTP/HTTPS"
})

// List firewall rules
proxmox_firewall_rules_list({
  node: "pve1",
  vmid: 100
})

🔒 权限级别

基本模式(PROXMOX_ALLOW_ELEVATED=false)

  • ✅ 列出节点、虚拟机、存储、群集状态
  • ✅ VM生命周期操作（启动、停止、关闭等）
  • ✅ 快照管理
  • ✅ 任务监控
  • ✅ 备份操作
  • ✅ 克隆和模板
  • ✅ 资源管理
  • ✅ 迁移
  • ✅ 防火墙管理

高架模式(PROXMOX_ALLOW_ELEVATED=true)

  • ✅ 所有基本功能
  • ✅ 详细的节点指标
  • ✅ 执行VM命令
  • ✅ 高级集群统计

所需权限：

  • 基础: VM.Audit, VM.PowerMgmt, VM.Backup, VM.Clone, VM.Config.Disk, VM.Config.Network, VM.Snapshot, Datastore.Audit
  • 升高的：添加 Sys.Audit, VM.Monitor, VM.Console

🔐 API令牌设置

  1. 登录Proxmox web界面
  2. 导航至 数据中心 → 权限 → API令牌
  3. 点击 添加:
    • 用户：选择用户（例如。， root@pam)
    • 令牌ID：输入名称（例如。， mcp-server)
    • 特权分离：取消选中以获得完全访问权限
  4. 复制 令牌ID 和 秘密 立即
  5. 产生 .env:
    PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

📊 日志记录

日志将写入：

  • logs/combined.log -所有日志（JSON格式）
  • logs/error.log -仅错误日志（JSON格式）
  • 控制台-漂亮的彩色印刷（显影）

配置日志级别：

LOG_LEVEL=debug   # Verbose logging
LOG_LEVEL=info    # Normal logging (default)
LOG_LEVEL=warn    # Warnings only
LOG_LEVEL=error   # Errors only

🐛 故障排除

构建错误

# Clean and rebuild
npm run clean
npm install
npm run build

连接错误

  1. 验证Proxmox是否可访问：

    curl -k https://YOUR_PROXMOX_HOST:8006/api2/json/version

  2. 测试API令牌：

    curl -k -H "Authorization: PVEAPIToken=USER!TOKEN=SECRET" \
  https://YOUR_PROXMOX_HOST:8006/api2/json/nodes

  3. 检查日志：

    tail -f logs/combined.log

权限错误

  • 确保API令牌具有所需的权限
  • 对于提升模式，添加 Sys.Audit, VM.Monitor, VM.Console
  • 检查令牌权限分离已禁用

🚀 发展

项目脚本

npm run build         # Build TypeScript
npm run build:watch   # Build with watch mode
npm run dev          # Development mode
npm run clean        # Clean dist directory
npm run typecheck    # Type checking only

添加新工具

  1. 在中创建工具文件 src/tools/
  2. 在中添加验证架构 src/validation.ts
  3. 注册 src/server.ts
  4. 更新中的类型定义 src/types.ts

🎯 生产特点

  • 🔒 安全 -基于令牌的身份验证
  • 🛡️ 健壮 -指数回退自动重试
  • 📊 可观察对象 -使用Winston进行结构化日志记录
  • ✅ 已验证 -所有34个工具都使用Zod验证
  • 🔄 坚韧的 -速率限制（100要求/分钟）
  • 🚀 快速 -具有优化构建的TypeScript
  • 📝 类型安全 -完全覆盖TypeScript
  • 🏗️ 模块化 -清晰的关注点分离（13个工具文件）

🤝 鸣谢

基于Python的原始实现 canvrno/ProxmoxMCP.

这个v2.2版本代表了一个完整的进化：

  • v1.0：基本监控（7个工具）
  • v2.0：使用生产特性重写TypeScript
  • v2.1:VM生命周期和快照管理（20个工具）
  • v2.2:完整的Proxmox管理套件（34个工具）

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关 MCP