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

权限模型

Level	Operations	Env Var Required
Basic	Read-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

工具分类

Domain	Tools	Key Operations	Reference
Nodes	47	Node status, network config, system ops, console access	proxmox-nodes.md
QEMU VMs	26	VM lifecycle, config, disks, network, commands	proxmox-vm.md
LXC Containers	20	Container lifecycle, config, mount points, network, exec	proxmox-lxc.md
VM/LXC Shared	22	Agent, firewall, migration (works for both)	proxmox-vm-lxc-shared.md
Snapshots & Backups	14	Create/restore snapshots, backup jobs	proxmox-snapshots-backups.md
Storage	16	Storage config, content, file operations, node disks	proxmox-storage.md
Networking	20	SDN (VNets, zones, controllers, subnets)	proxmox-networking.md
Cluster	54	HA, firewall, aliases, ipsets, backup jobs, replication, config	proxmox-cluster.md
Access Control	25	Users, groups, roles, ACLs, domains, API tokens	proxmox-access-control.md
Ceph	16	Ceph OSDs, MONs, MDS, pools, filesystems	proxmox-ceph.md
Pools	5	Resource pool management	proxmox-pools.md
Certificates	7	Node certificates, custom SSL, ACME ordering	proxmox-certificates.md
ACME	8	ACME accounts, plugins, directories	proxmox-acme.md
Notifications	5	Notification targets, SMTP/Gotify testing	proxmox-notifications.md

Total: 92 tools

领域	工具数量	核心操作	参考文档
节点管理	47	节点状态、网络配置、系统操作、控制台访问	proxmox-nodes.md
QEMU虚拟机	26	虚拟机生命周期、配置、磁盘、网络、命令执行	proxmox-vm.md
LXC容器	20	容器生命周期、配置、挂载点、网络、执行命令	proxmox-lxc.md
VM/LXC通用工具	22	Agent、防火墙、迁移（适用于两者）	proxmox-vm-lxc-shared.md
快照与备份	14	创建/恢复快照、备份任务	proxmox-snapshots-backups.md
存储管理	16	存储配置、内容管理、文件操作、节点磁盘	proxmox-storage.md
网络管理	20	SDN（虚拟网络、区域、控制器、子网）	proxmox-networking.md
集群管理	54	高可用、防火墙、别名、IP集、备份任务、复制、配置	proxmox-cluster.md
访问控制	25	用户、组、角色、ACL、域、API令牌	proxmox-access-control.md
Ceph存储	16	Ceph OSD、MON、MDS、存储池、文件系统	proxmox-ceph.md
资源池	5	资源池管理	proxmox-pools.md
证书管理	7	节点证书、自定义SSL、ACME申请	proxmox-certificates.md
ACME管理	8	ACME账户、插件、目录	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

备份

proxmox_backup → Create backup to storage
proxmox_backup → Verify backup exists

proxmox_backup → 创建备份到存储
proxmox_backup → 验证备份存在

Restore

恢复

proxmox_backup → Find backup file
proxmox_backup → Restore to new/existing VM

undefined

proxmox_backup → 查找备份文件
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

使用技巧

Always check permissions: Use basic tools first, only enable elevated when needed
Verify before destructive ops: Use
```
get_vm_status
```
before
```
delete_vm
```
Use snapshots: Create snapshot before major changes
Monitor tasks: Use
```
get_node_tasks
```
to track long-running operations
Handle 500 errors: Proxmox sometimes returns 500 instead of 404 - check context
SSL mode for self-signed: Most Proxmox installations use self-signed certs - use
```
verify
```
mode

始终检查权限: 优先使用基础工具，仅在需要时启用高级权限
破坏性操作前验证: 删除虚拟机前先使用
```
get_vm_status
```
确认
使用快照: 重大变更前创建快照
监控任务: 使用
```
get_node_tasks
```
跟踪长时间运行的操作
处理500错误: Proxmox有时会返回500而非404错误——需结合上下文判断
自签名证书的SSL模式: 大多数Proxmox安装使用自签名证书——建议使用
```
verify
```
模式

License

许可证

MIT License - Part of @bldg-7/proxmox-mcp package

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