Back to Details

proxmox-mcp-tools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Proxmox MCP Tools Reference

Proxmox MCP工具参考

AI Agent Skill: Complete reference for 92 Proxmox Virtual Environment management tools via Model Context Protocol
AI Agent Skill: 通过Model Context Protocol（MCP）管理Proxmox Virtual Environment的92款工具完整参考

Overview

概述

This skill teaches AI agents how to use the @bldg-7/proxmox-mcp server, which provides 92 comprehensive tools for managing Proxmox VE infrastructure through the Model Context Protocol (MCP).
What you'll learn:
  • How to connect to Proxmox VE via MCP
  • 92 tools organized into 14 functional domains
  • Permission model (basic vs elevated operations)
  • Common workflows and patterns
  • Troubleshooting API quirks
Target audience: AI agents managing Proxmox infrastructure, automating VM/LXC provisioning, monitoring cluster health, or performing operational tasks.
本技能指导AI Agent如何使用**@bldg-7/proxmox-mcp**服务器，该服务器通过Model Context Protocol（MCP）提供92款全面的工具，用于管理Proxmox VE基础设施。
你将学到:
  • 如何通过MCP连接到Proxmox VE
  • 按14个功能领域分类的92款工具
  • 权限模型（基础操作 vs 高级操作）
  • 常见工作流与模式
  • API异常问题排查
目标受众：管理Proxmox基础设施、自动化VM/LXC部署、监控集群健康状况或执行运维任务的AI Agent。

Quick Start

快速开始

Connection Setup

连接设置

Required Environment Variables:
bash
PROXMOX_HOST=pve.example.com
PROXMOX_TOKEN_NAME=mytoken
PROXMOX_TOKEN_VALUE=abc123-def456-ghi789
Optional Configuration:
bash
PROXMOX_USER=root@pam          # Default: root@pam
PROXMOX_SSL_MODE=verify         # strict|verify|insecure (default: strict)
PROXMOX_ALLOW_ELEVATED=true     # Enable create/modify/delete (default: false)
PROXMOX_PORT=8006               # Default: 8006
SSH Configuration (for 
proxmox_lxc_exec
):
bash
PROXMOX_SSH_ENABLED=true        # Enable SSH-based LXC exec (default: false)
PROXMOX_SSH_HOST=pve.example.com # SSH host (falls back to PROXMOX_HOST)
PROXMOX_SSH_PORT=22             # SSH port (default: 22)
PROXMOX_SSH_USER=root           # SSH username (default: root)
PROXMOX_SSH_KEY_PATH=~/.ssh/id_rsa # Path to SSH private key (required when SSH enabled)
PROXMOX_SSH_NODE=pve1           # Proxmox node name (required when SSH enabled)
PROXMOX_SSH_HOST_KEY_FINGERPRINT=sha256:... # Optional host key verification
所需环境变量:
bash
PROXMOX_HOST=pve.example.com
PROXMOX_TOKEN_NAME=mytoken
PROXMOX_TOKEN_VALUE=abc123-def456-ghi789
可选配置:
bash
PROXMOX_USER=root@pam          # 默认值: root@pam
PROXMOX_SSL_MODE=verify         # strict|verify|insecure (默认值: strict)
PROXMOX_ALLOW_ELEVATED=true     # 启用创建/修改/删除操作 (默认值: false)
PROXMOX_PORT=8006               # 默认值: 8006
SSH配置（用于
proxmox_lxc_exec
）:
bash
PROXMOX_SSH_ENABLED=true        # 启用基于SSH的LXC执行功能 (默认值: false)
PROXMOX_SSH_HOST=pve.example.com # SSH主机（默认回退到PROXMOX_HOST）
PROXMOX_SSH_PORT=22             # SSH端口 (默认值: 22)
PROXMOX_SSH_USER=root           # SSH用户名 (默认值: root)
PROXMOX_SSH_KEY_PATH=~/.ssh/id_rsa # SSH私钥路径（启用SSH时必填）
PROXMOX_SSH_NODE=pve1           # Proxmox节点名称（启用SSH时必填）
PROXMOX_SSH_HOST_KEY_FINGERPRINT=sha256:... # 可选主机密钥验证

Permission Model

权限模型

LevelOperationsEnv Var Required
BasicRead-only (list, get, status)None
Elevated 🔒Create, modify, delete
PROXMOX_ALLOW_ELEVATED=true
102 basic tools + 207 elevated tools = 92 total
权限级别操作范围所需环境变量
基础权限只读（列表、查询、状态查看）无
高级权限 🔒创建、修改、删除
PROXMOX_ALLOW_ELEVATED=true
102个基础工具 + 207个高级工具 = 总计92款工具

SSL Modes

SSL模式

  • strict
    : Full certificate verification (production)
  • verify
    : Allow self-signed certificates (common for Proxmox)
  • insecure
    : No verification (development only)
  • strict
    : 完整证书验证（生产环境）
  • verify
    : 允许自签名证书（Proxmox常用配置）
  • insecure
    : 无验证（仅开发环境）

Tool Categories

工具分类

DomainToolsKey OperationsReference
Nodes47Node status, network config, system ops, console accessproxmox-nodes.md
QEMU VMs26VM lifecycle, config, disks, network, commandsproxmox-vm.md
LXC Containers20Container lifecycle, config, mount points, network, execproxmox-lxc.md
VM/LXC Shared22Agent, firewall, migration (works for both)proxmox-vm-lxc-shared.md
Snapshots & Backups14Create/restore snapshots, backup jobsproxmox-snapshots-backups.md
Storage16Storage config, content, file operations, node disksproxmox-storage.md
Networking20SDN (VNets, zones, controllers, subnets)proxmox-networking.md
Cluster54HA, firewall, aliases, ipsets, backup jobs, replication, configproxmox-cluster.md
Access Control25Users, groups, roles, ACLs, domains, API tokensproxmox-access-control.md
Ceph16Ceph OSDs, MONs, MDS, pools, filesystemsproxmox-ceph.md
Pools5Resource pool managementproxmox-pools.md
Certificates7Node certificates, custom SSL, ACME orderingproxmox-certificates.md
ACME8ACME accounts, plugins, directoriesproxmox-acme.md
Notifications5Notification targets, SMTP/Gotify testingproxmox-notifications.md
Total: 92 tools
领域工具数量核心操作参考文档
节点管理47节点状态、网络配置、系统操作、控制台访问proxmox-nodes.md
QEMU虚拟机26虚拟机生命周期、配置、磁盘、网络、命令执行proxmox-vm.md
LXC容器20容器生命周期、配置、挂载点、网络、执行命令proxmox-lxc.md
VM/LXC通用工具22Agent、防火墙、迁移（适用于两者）proxmox-vm-lxc-shared.md
快照与备份14创建/恢复快照、备份任务proxmox-snapshots-backups.md
存储管理16存储配置、内容管理、文件操作、节点磁盘proxmox-storage.md
网络管理20SDN（虚拟网络、区域、控制器、子网）proxmox-networking.md
集群管理54高可用、防火墙、别名、IP集、备份任务、复制、配置proxmox-cluster.md
访问控制25用户、组、角色、ACL、域、API令牌proxmox-access-control.md
Ceph存储16Ceph OSD、MON、MDS、存储池、文件系统proxmox-ceph.md
资源池5资源池管理proxmox-pools.md
证书管理7节点证书、自定义SSL、ACME申请proxmox-certificates.md
ACME管理8ACME账户、插件、目录proxmox-acme.md
通知管理5通知目标、SMTP/Gotify测试proxmox-notifications.md
总计: 92款工具

Common Workflows

常见工作流

1. Create and Configure a VM

1. 创建并配置虚拟机

1. proxmox_get_next_vmid → Get available VM ID
2. proxmox_create_vm → Create VM with basic config
3. proxmox_vm_disk → Attach storage
4. proxmox_guest_network → Configure network
5. proxmox_guest_start → Power on
6. proxmox_guest_status → Verify running
1. proxmox_get_next_vmid → 获取可用的虚拟机ID
2. proxmox_create_vm → 创建基础配置的虚拟机
3. proxmox_vm_disk → 挂载存储
4. proxmox_guest_network → 配置网络
5. proxmox_guest_start → 开机
6. proxmox_guest_status → 验证运行状态

2. Clone VM for Testing

2. 克隆虚拟机用于测试

1. proxmox_guest_config → Review source VM
2. proxmox_guest_snapshot → Snapshot before clone
3. proxmox_guest_clone → Create clone (full or linked)
4. proxmox_guest_start → Start cloned VM
1. proxmox_guest_config → 查看源虚拟机配置
2. proxmox_guest_snapshot → 克隆前创建快照
3. proxmox_guest_clone → 创建克隆（完整或链接克隆）
4. proxmox_guest_start → 启动克隆后的虚拟机

3. Backup and Restore

3. 备份与恢复

undefined
undefined

Backup

备份

  1. proxmox_backup → Create backup to storage
  2. proxmox_backup → Verify backup exists
  1. proxmox_backup → 创建备份到存储
  2. proxmox_backup → 验证备份存在

Restore

恢复

  1. proxmox_backup → Find backup file
  2. proxmox_backup → Restore to new/existing VM
undefined
  1. proxmox_backup → 查找备份文件
  2. proxmox_backup → 恢复到新虚拟机/现有虚拟机
undefined

4. Migrate VM Between Nodes

4. 跨节点迁移虚拟机

1. proxmox_node → List available target nodes
2. proxmox_guest_status → Check VM is running
3. proxmox_guest_migrate → Live or offline migration
4. proxmox_guest_status → Verify on new node
1. proxmox_node → 列出可用的目标节点
2. proxmox_guest_status → 检查虚拟机是否运行
3. proxmox_guest_migrate → 在线或离线迁移
4. proxmox_guest_status → 验证虚拟机在新节点的状态

5. Configure HA for Critical VMs

5. 为关键虚拟机配置高可用

1. proxmox_ha_group → Define node group
2. proxmox_ha_resource → Add VM to HA
3. proxmox_ha_resource → Monitor HA state
1. proxmox_ha_group → 定义节点组
2. proxmox_ha_resource → 将虚拟机添加到高可用组
3. proxmox_ha_resource → 监控高可用状态

6. Monitor Cluster Health

6. 监控集群健康状况

1. proxmox_cluster → Overall cluster state
2. proxmox_node → Node-level health
3. proxmox_node_task → Recent operations
4. proxmox_ceph → Ceph cluster (if used)
1. proxmox_cluster → 集群整体状态
2. proxmox_node → 节点级健康状况
3. proxmox_node_task → 近期操作记录
4. proxmox_ceph → Ceph集群状态（若使用）

7. Manage Storage

7. 存储管理

1. proxmox_storage_config → Available storage
2. proxmox_storage_content → Browse content
3. proxmox_storage_content → Upload ISO/template
4. proxmox_storage_content → Clean old backups
More workflows: See proxmox-workflows.md
1. proxmox_storage_config → 查看可用存储
2. proxmox_storage_content → 浏览存储内容
3. proxmox_storage_content → 上传ISO/模板
4. proxmox_storage_content → 清理旧备份
更多工作流: 查看 proxmox-workflows.md

Troubleshooting Quick Reference

问题排查快速参考

1. Connection Refused

1. 连接被拒绝

Symptom: 
ECONNREFUSED
or timeout
Fix: Verify 
PROXMOX_HOST
, check port 8006, firewall rules
症状: 
ECONNREFUSED
或超时
解决方法: 验证
PROXMOX_HOST
，检查8006端口，确认防火墙规则

2. Authentication Failed

2. 认证失败

Symptom: 
401 Unauthorized

Fix: Verify token name/value, ensure token has permissions in Proxmox
症状: 
401 Unauthorized

解决方法: 验证令牌名称/值，确保令牌在Proxmox中拥有对应权限

3. SSL Certificate Errors

3. SSL证书错误

Symptom: 
UNABLE_TO_VERIFY_LEAF_SIGNATURE

Fix: Use 
PROXMOX_SSL_MODE=verify
for self-signed certs
症状: 
UNABLE_TO_VERIFY_LEAF_SIGNATURE

解决方法: 对于自签名证书，使用
PROXMOX_SSL_MODE=verify
模式

4. Permission Denied

4. 权限被拒绝

Symptom: 
🚫 Permission Denied

Fix: Set 
PROXMOX_ALLOW_ELEVATED=true
for create/modify/delete operations
症状: 
🚫 Permission Denied

解决方法: 执行创建/修改/删除操作时，设置
PROXMOX_ALLOW_ELEVATED=true

5. VM Not Found (500 instead of 404)

5. 虚拟机未找到（返回500而非404）

Symptom: API returns 500 error for missing VM
Fix: This is a Proxmox API quirk - treat 500 as "not found" in some contexts
More troubleshooting: See proxmox-troubleshooting.md
症状: API对不存在的虚拟机返回500错误
解决方法: 这是Proxmox API的特性——在某些场景下将500错误视为“未找到”
更多排查内容: 查看 proxmox-troubleshooting.md

Tool Response Format

工具响应格式

All tools return structured MCP responses:
Success:
json
{
  "content": [{"type": "text", "text": "✅ Operation successful\n\n• Details..."}],
  "isError": false
}
Error:
json
{
  "content": [{"type": "text", "text": "❌ Error: Reason..."}],
  "isError": true
}
Permission Denied:
json
{
  "content": [{"type": "text", "text": "🚫 Permission Denied: Set PROXMOX_ALLOW_ELEVATED=true"}],
  "isError": true
}
所有工具均返回结构化MCP响应:
成功响应:
json
{
  "content": [{"type": "text", "text": "✅ 操作成功\n\n• 详情..."}],
  "isError": false
}
错误响应:
json
{
  "content": [{"type": "text", "text": "❌ 错误: 原因..."}],
  "isError": true
}
权限拒绝响应:
json
{
  "content": [{"type": "text", "text": "🚫 权限拒绝: 请设置PROXMOX_ALLOW_ELEVATED=true"}],
  "isError": true
}

References

参考文档

Domain-Specific Documentation

领域专属文档

  • proxmox-nodes.md - Node management, network config, system operations (47 tools)
  • proxmox-vm.md - QEMU VM operations (26 tools)
  • proxmox-lxc.md - LXC container operations (20 tools)
  • proxmox-vm-lxc-shared.md - Shared VM/LXC operations (22 tools)
  • proxmox-snapshots-backups.md - Snapshots and backups (14 tools)
  • proxmox-storage.md - Storage management (16 tools)
  • proxmox-networking.md - SDN configuration (20 tools)
  • proxmox-cluster.md - Cluster operations (54 tools)
  • proxmox-access-control.md - Users, roles, ACLs, API tokens (25 tools)
  • proxmox-ceph.md - Ceph storage cluster (16 tools)
  • proxmox-pools.md - Resource pools (5 tools)
  • proxmox-certificates.md - Certificate management (7 tools)
  • proxmox-acme.md - ACME account and plugin management (8 tools)
  • proxmox-notifications.md - Notification targets (5 tools)
  • proxmox-nodes.md - 节点管理、网络配置、系统操作（47款工具）
  • proxmox-vm.md - QEMU虚拟机操作（26款工具）
  • proxmox-lxc.md - LXC容器操作（20款工具）
  • proxmox-vm-lxc-shared.md - VM/LXC通用操作（22款工具）
  • proxmox-snapshots-backups.md - 快照与备份（14款工具）
  • proxmox-storage.md - 存储管理（16款工具）
  • proxmox-networking.md - SDN配置（20款工具）
  • proxmox-cluster.md - 集群操作（54款工具）
  • proxmox-access-control.md - 用户、角色、ACL、API令牌（25款工具）
  • proxmox-ceph.md - Ceph存储集群（16款工具）
  • proxmox-pools.md - 资源池（5款工具）
  • proxmox-certificates.md - 证书管理（7款工具）
  • proxmox-acme.md - ACME账户与插件管理（8款工具）
  • proxmox-notifications.md - 通知目标（5款工具）

Operational Guides

运维指南

  • proxmox-workflows.md - Common operational patterns
  • proxmox-troubleshooting.md - API quirks and solutions
  • proxmox-workflows.md - 常见运维模式
  • proxmox-troubleshooting.md - API特性与解决方案

Usage Tips

使用技巧

  1. Always check permissions: Use basic tools first, only enable elevated when needed
  2. Verify before destructive ops: Use 
    get_vm_status
    before 
    delete_vm
  3. Use snapshots: Create snapshot before major changes
  4. Monitor tasks: Use 
    get_node_tasks
    to track long-running operations
  5. Handle 500 errors: Proxmox sometimes returns 500 instead of 404 - check context
  6. SSL mode for self-signed: Most Proxmox installations use self-signed certs - use 
    verify
    mode
  1. 始终检查权限: 优先使用基础工具，仅在需要时启用高级权限
  2. 破坏性操作前验证: 删除虚拟机前先使用
    get_vm_status
    确认
  3. 使用快照: 重大变更前创建快照
  4. 监控任务: 使用
    get_node_tasks
    跟踪长时间运行的操作
  5. 处理500错误: Proxmox有时会返回500而非404错误——需结合上下文判断
  6. 自签名证书的SSL模式: 大多数Proxmox安装使用自签名证书——建议使用
    verify
    模式

License

许可证

MIT License - Part of @bldg-7/proxmox-mcp package
MIT许可证 - 属于@bldg-7/proxmox-mcp包的一部分