Proxmox虚拟化管理工具

Proxmox MCP服务器

Proxmox虚拟环境的模型上下文协议（MCP）服务器

英语 | 韩语

一个全面的MCP服务器，提供92个用于管理Proxmox虚拟环境的工具，包括QEMU VM和LXC容器。

学分和背景

这个项目是对TypeScript的重写 mcp-proxmox服务器，它本身就是原始Python实现的Node.js端口 canvrno/ProxmoxMCP.

发生了什么变化

建筑学:

• 3147行单文件单体→ 跨110多个源文件的模块化TypeScript
• 无类型安全→ 严格的TypeScript noUncheckedIndexedAccess
• 手写JSON模式→ 具有自动JSON模式生成功能的Zod模式
• 巨人开关声明（55例）→ 带有处理程序/模式对的工具注册表

质量:

• 0测试→ 1,134测试
• 无输入验证→ 在每次工具调用时进行Zod运行时验证
• 隐式错误处理→ 带上下文的结构化MCP错误响应
• 无权限检查→ 两层权限模型（基本/高级）

开发者体验:

• npx @bldg-7/proxmox-mcp 管用就行
• 通过MCP公开的所有92个工具描述 ListTools
• 包含速率限制器中间件
• Pino结构化日志记录，而不是 console.log

特征

• 92种综合工具 用于Proxmox管理
• 完整的TypeScript实现 具有严格的型号安全性
• 支持QEMU VM和LXC容器
• 安全认证 （API令牌）
• 灵活的SSL模式 （严格、验证、不安全）
• 基于权限的访问控制 （基础操作与高级操作）
• 全面的错误处理 结构化响应
• 基于MCP SDK 1.25.3构建

安装

npm install @bldg-7/proxmox-mcp
# or
pnpm add @bldg-7/proxmox-mcp
# or
yarn add @bldg-7/proxmox-mcp

配置

环境变量

启动服务器之前，请设置以下环境变量：

SSL模式

• strict：针对系统CA存储的完整SSL证书验证（建议用于生产）
• verify：与 strict，但另外信任通过提供的CA证书 PROXMOX_SSL_CA_CERT。对于自签名证书，点 PROXMOX_SSL_CA_CERT 在PEM格式的服务器证书（或您的内部CA）上。没有 PROXMOX_SSL_CA_CERT，此模式的行为与 strict.
• insecure：无SSL验证（仅用于开发，不推荐）

不要使用 NODE_TLS_REJECT_UNAUTHORIZED=0 为了解决证书错误，它会禁用整个进程的TLS验证，并在设置时记录警告。使用 PROXMOX_SSL_MODE 和 PROXMOX_SSL_CA_CERT 相反。

权限模型

服务器实现了一个两层权限模型：

• 基本操作：只读操作（列表、获取、状态）-始终允许
• 高架作业：创建、修改、删除操作-需要 PROXMOX_ALLOW_ELEVATED=true

这可以防止意外的破坏性操作，并提供额外的安全层。

用法

启动服务器

# With environment variables
export PROXMOX_HOST=pve.example.com
export PROXMOX_TOKEN_NAME=mytoken
export PROXMOX_TOKEN_VALUE=abc123-def456-ghi789
export PROXMOX_SSL_MODE=verify
export PROXMOX_SSL_CA_CERT=/path/to/proxmox-ca.pem  # needed with verify for self-signed certs
export PROXMOX_ALLOW_ELEVATED=true

npx @bldg-7/proxmox-mcp

与Claude Desktop一起使用

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@bldg-7/proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "pve.example.com",
        "PROXMOX_TOKEN_NAME": "mytoken",
        "PROXMOX_TOKEN_VALUE": "abc123-def456-ghi789",
        "PROXMOX_SSL_MODE": "verify",
        "PROXMOX_SSL_CA_CERT": "/path/to/proxmox-ca.pem",
        "PROXMOX_ALLOW_ELEVATED": "true"
      }
    }
  }
}

可用工具

此服务器提供 92种综合工具 对于Proxmox管理：

📖 完整工具参考→

代理技能

此套餐包括 代理技能 -AI优化的文档，教导代理如何使用Proxmox MCP工具和操作最佳实践。技能遵循 agentskills.io 网站 开放标准，可跨多个AI代理平台工作。

可用技能

安装

代理技能标准 （克劳德代码、OpenCode、游标、Codex、Gemini CLI、VS代码）：

npx skills add Bldg-7/proxmox-mcp

对于Claude代码插件:

/plugin marketplace add Bldg-7/proxmox-mcp

支持的代理

• Claude 代码 -Anthropic官方CLI
• 开源代码 -开源Claude代码替代方案
• 光标 -AI驱动的代码编辑器
• 法典 -GitHub Copilot命令行界面
• 双子星命令行工具 -谷歌的人工智能助手
• VS Code -通过代理技能扩展

技能提供渐进式披露：元数据（~100个令牌）→ 指令（<5000个令牌）→ 详细参考资料（按需）。

技能如何发挥作用

安装后，技能会自动加载到代理的上下文中。代理学习Proxmox工具的使用、工作流程和最佳实践，因此您可以给出自然语言指令，代理将其转换为正确的MCP工具调用。

示例——创建虚拟机 （代理人使用 proxmox-mcp-tools 技能）：

You: "Create an Ubuntu VM with 4 cores, 8GB RAM, and 50GB disk on pve1"

Agent knows the workflow from the skill:
  1. proxmox_get_next_vmid        → gets available VM ID (e.g., 105)
  2. proxmox_create_vm            → creates VM 105 with 4 cores, 8GB RAM
  3. proxmox_vm_disk              → attaches 50GB virtio disk (action: 'add')
  4. proxmox_guest_network        → adds network interface on vmbr0 (action: 'add', type: 'vm')
  5. proxmox_guest_start          → powers on the VM (type: 'vm')

示例——设置HA （代理人使用 proxmox-admin 技能）：

You: "Make VM 100 highly available"

Agent knows the operational playbook:
  1. proxmox_ha_group             → checks existing HA groups (action: 'list')
  2. proxmox_ha_resource          → adds VM 100 to HA with priority (action: 'create')
  3. proxmox_ha_resource          → verifies HA is active (action: 'status')

示例——故障排除 （代理人同时使用这两种技能）：

You: "VM 100 won't start, help me figure out why"

Agent combines tool knowledge + operational expertise:
  1. proxmox_guest_status         → checks current state (type: 'vm')
  2. proxmox_guest_config         → reviews configuration (action: 'get', type: 'vm')
  3. proxmox_node                 → checks node resource availability (action: 'status')
  4. proxmox_node_task            → finds recent failed tasks (action: 'list')
  → Diagnoses: "Node pve1 has insufficient memory. VM requires 8GB but only 2GB free."
  → Suggests: resize VM memory, migrate to another node, or free resources

技能内容

proxmox mcp工具 --工具参考：

• 92个工具分为14个域（VM、LXC、集群、存储、网络、Ceph、访问控制、池、证书、ACME、通知）
• 每个工具的参数、类型和描述
• 权限级别（基本与高级）🔒)
• 常见的工作流程模式（创建虚拟机、备份/恢复、克隆、迁移）

Proxmox管理员 --运营专长：

• VM&LXC生命周期手册（创建→ 配置→ 监视器→ 备份→ 退役）
• 存储管理策略（Ceph、NFS、LVM、ZFS）
• HA配置和故障转移过程
• 常见API异常故障排除指南
• 安全最佳实践（权限模型、令牌管理）
• 性能监控和优化

子代理

此套餐包括 子代理 -用于执行特定域Proxmox操作的专用AI代理。技能提供知识（“这是工具以及如何使用它们”），而子代理提供行动（“我会为你做这件事”）。子代理自动加载相关技能，并使用MCP工具执行操作。

可用子代理

子代理如何工作

子代理使用 汽车代表团 在Claude Code和兼容平台中：

1. 用户提出请求：“创建一个具有4个内核和8GB RAM的新Ubuntu VM”
2. 克劳德分析请求：根据示例块将请求匹配到vm管理器代理
3. 汽车代表：使用完整上下文调用vm管理器代理
4. 代理执行：vm管理器加载技能，调用MCP工具，完成操作
5. 返回结果：带有操作细节的结构化响应

先决条件

• MCP服务器：必须连接并配置Proxmox MCP服务器
• 技能：子代理自动加载 proxmox-mcp-tools 和 proxmox-admin 技能
• 权限：高架作业需要 PROXMOX_ALLOW_ELEVATED=true 在MCP服务器配置中

安装

安装插件时包含子代理：

对于Claude代码插件:

/plugin marketplace add Bldg-7/proxmox-mcp

代理技能标准 （如果支持）：

npx skills add Bldg-7/proxmox-mcp

使用示例

创建虚拟机 （自动委托给vm管理器）：

User: "Create a new Ubuntu VM with 4 cores, 8GB RAM, and a 50GB disk on node pve1"
→ vm-manager executes: get next VMID → create VM → add disk → add network → start

启用HA （自动委派给集群管理员）：

User: "Enable high availability for VM 100 with priority 100"
→ cluster-admin executes: check HA config → add HA resource → verify

监视器集群 （自动委派监视）：

User: "Show me the current cluster status and any issues"
→ monitor executes: get cluster status → get HA status → get nodes → report

代理域边界

每个子代理都有明确的责任来避免重叠：

• 虚拟机管理器：仅QEMU虚拟机（非LXC）。将集群操作委托给集群管理员。
• lxc经理：仅LXC容器（非VM）。将集群操作委托给集群管理员。
• 集群管理员：集群范围的操作（HA、防火墙别名/ipset、集群配置、通知）。将每个VM/LXC操作委托给各自的管理者。
• 存储管理员：存储基础架构、证书管理、ACME配置、高级磁盘操作。将VM磁盘操作委托给VM管理器。
• 网络设定：仅网络基础设施。将每个VM/LXC NIC的代表分配给各自的经理。
• 访问管理员：访问控制，包括API令牌管理。不得委托其他代理人。
• 监视器：只读监控，包括节点度量/RRD数据。将所有操作委托给适当的代理。

错误处理

所有工具均按照MCP协议返回结构化响应：

成功响应

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

错误响应

{
  "content": [
    {
      "type": "text",
      "text": "❌ Error: Operation failed\n\nReason: Detailed error message"
    }
  ],
  "isError": true
}

权限不足

{
  "content": [
    {
      "type": "text",
      "text": "🚫 Permission Denied: Operation requires elevated permissions\n\nSet PROXMOX_ALLOW_ELEVATED=true to enable this operation."
    }
  ],
  "isError": true
}

故障排除

连接问题

问题: ECONNREFUSED 或连接超时

解决方案:

• 验证 PROXMOX_HOST 正确且可访问
• 检查 PROXMOX_PORT （默认值：8006）
• 确保防火墙允许连接到Proxmox API端口
• 尝试 PROXMOX_SSL_MODE=insecure 用于测试（不建议用于生产）

身份验证错误

问题: 401 Unauthorized 或身份验证失败

解决方案:

• 验证 PROXMOX_USER 如果设置，则包括领域（例如。， root@pam，不仅 root)
• 验证 PROXMOX_TOKEN_NAME 和 PROXMOX_TOKEN_VALUE 有效
• 确保API令牌在Proxmox中具有足够的权限

SSL证书错误

问题: UNABLE_TO_VERIFY_LEAF_SIGNATURE 或SSL错误

解决方案:

• 对于自签名证书，设置 PROXMOX_SSL_MODE=verify 和 PROXMOX_SSL_CA_CERT=/path/to/cert.pem （服务器证书或您的内部CA）-- verify 没有 PROXMOX_SSL_CA_CERT 表现得像 strict 仍然失败
• 使用 PROXMOX_SSL_MODE=insecure 用于开发（不建议用于生产）
• 在Proxmox服务器上安装正确的SSL证书以供生产使用
• 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0；它在整个过程中禁用TLS验证

权限被拒绝错误

问题: 🚫 Permission Denied 用于操作

解决方案:

• 集 PROXMOX_ALLOW_ELEVATED=true 实现高空作业
• 查看哪些操作需要提升权限（标记为🔒)
• 确保这是有意的-提升的操作可以修改/删除资源

发展

从源头构建

git clone https://github.com/Bldg-7/proxmox-mcp.git
cd proxmox-mcp
pnpm install
pnpm build

运行测试

pnpm test              # Run tests once
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Run tests with coverage report

类型检查

pnpm typecheck         # Type check without emitting files

代码检查

pnpm lint              # Run ESLint

贡献

欢迎投稿！请参阅 贡献.md 作为指导方针。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 内置于 模型上下文协议SDK
• 由...驱动 Proxmox虚拟环境

传说: 🔒 = 需要提升权限(PROXMOX_ALLOW_ELEVATED=true)