proxmox-mcp-tools

Proxmox MCP 工具参考

AI Agent 技能：通过 Model Context Protocol 完整参考 92 个 Proxmox Virtual Environment 管理工具

概述

本技能将介绍 AI Agent 如何使用 @bldg-7/proxmox-mcp 服务，该服务通过 Model Context Protocol（MCP）提供 92 个全面的工具，用于管理 Proxmox VE 基础设施。

你将了解：

• 如何通过 MCP 连接 Proxmox VE
• 按 14 个功能领域分类的 92 个工具
• 权限模型（基本操作与提升权限操作）
• 常见工作流和模式
• API 特性的故障排除方法

目标受众：管理 Proxmox 基础设施、自动化 VM/LXC 配置、监控集群运行状况或执行运维任务的 AI Agent。

---

快速开始

连接设置

必需的环境变量：

PROXMOX_HOST=pve.example.com
PROXMOX_TOKEN_NAME=mytoken
PROXMOX_TOKEN_VALUE=abc123-def456-ghi789

可选配置：

PROXMOX_USER=root@pam          # Default: root@pam
PROXMOX_SSL_MODE=verify         # strict|verify|insecure (default: strict)
PROXMOX_SSL_CA_CERT=/path/ca.pem # CA cert (PEM) trusted in verify mode — required for self-signed certs
PROXMOX_ALLOW_ELEVATED=true     # Enable create/modify/delete (default: false)
PROXMOX_PORT=8006               # Default: 8006
PROXMOX_LOG_LEVEL=info          # trace|debug|info|warn|error|fatal (default: info)

SSH 配置（用于 proxmox_lxc_exec）：

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

权限模型

级别	操作	必需的环境变量
基本	只读（列表、获取、状态）	无
提升权限 🔒	创建、修改、删除	PROXMOX_ALLOW_ELEVATED=true

共 92 个工具 — 读取操作属于基本权限；创建、修改和删除操作需要提升权限（许多工具支持混合操作：是否需要提升权限取决于 action）

SSL 模式

• strict：完整验证证书（生产环境）
• verify：与 strict 类似，另外信任来自 PROXMOX_SSL_CA_CERT 的 CA — 自签名证书需要设置此项；未设置时与 strict 完全相同
• insecure：不进行验证（仅限开发环境）

---

工具类别

领域	工具数	主要操作	参考
节点	47	节点状态、网络配置、系统操作、控制台访问	proxmox-nodes.md
QEMU VM	26	VM 生命周期、配置、磁盘、网络、命令	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（VNet、区域、控制器、子网）	proxmox-networking.md
集群	54	HA、防火墙、别名、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 个工具

---

常见工作流

1. 创建并配置 VM

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

2. 克隆 VM 用于测试

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

3. 备份与还原

# Backup
1. proxmox_backup → Create backup to storage
2. proxmox_backup → Verify backup exists

# Restore
1. proxmox_backup → Find backup file
2. proxmox_backup → Restore to new/existing VM

4. 在节点之间迁移 VM

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

5. 为关键 VM 配置 HA

1. proxmox_ha_group → Define node group
2. proxmox_ha_resource → Add VM to HA
3. proxmox_ha_resource → Monitor HA state

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)

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

更多工作流：参见 proxmox-workflows.md

---

故障排除速查参考

1. 连接被拒绝

症状：ECONNREFUSED 或超时
修复方法：验证 PROXMOX_HOST，检查端口 8006 和防火墙规则

2. 身份验证失败

症状：401 Unauthorized
修复方法：验证令牌名称/值，确保令牌在 Proxmox 中具有相应权限

3. SSL 证书错误

症状：UNABLE_TO_VERIFY_LEAF_SIGNATURE
修复方法：对于自签名证书，使用 PROXMOX_SSL_MODE=verify

4. 权限被拒绝

症状：🚫 Permission Denied
修复方法：对于创建/修改/删除操作，设置 PROXMOX_ALLOW_ELEVATED=true

5. 找不到 VM（返回 500 而不是 404）

症状：找不到 VM 时，API 返回 500 错误
修复方法：这是 Proxmox API 的一个特殊情况——在某些场景下，将 500 视为“未找到”

更多故障排除信息：请参阅 proxmox-troubleshooting.md

---

工具响应格式

所有工具都会返回结构化的 MCP 响应：

成功：

{
  "content": [{"type": "text", "text": "✅ Operation successful\n\n• Details..."}],
  "isError": false
}

错误：

{
  "content": [{"type": "text", "text": "❌ Error: Reason..."}],
  "isError": true
}

权限被拒绝：

{
  "content": [{"type": "text", "text": "🚫 Permission Denied: Set PROXMOX_ALLOW_ELEVATED=true"}],
  "isError": true
}

---

参考资料

特定领域文档

• proxmox-nodes.md - 节点管理、网络配置、系统操作（47 个工具）
• proxmox-vm.md - QEMU VM 操作（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 个工具）

运维指南

• proxmox-workflows.md - 常见运维模式
• proxmox-troubleshooting.md - API 特殊情况及解决方案

---

使用提示

1. 始终检查权限：先使用基础工具，仅在需要时启用提升权限
2. 执行破坏性操作前先验证：在使用 delete_vm 前，先使用 get_vm_status
3. 使用快照：进行重大更改前创建快照
4. 监控任务：使用 get_node_tasks 跟踪长时间运行的操作
5. 处理 500 错误：Proxmox 有时会返回 500 而不是 404——请结合具体场景判断
6. 自签名证书的 SSL 模式：大多数 Proxmox 安装使用自签名证书——请使用 verify 模式

---

许可证

MIT 许可证 - 属于 @bldg-7/proxmox-mcp 软件包