AI导哈

Proxmox集群监控协议

一个只读的Proxmox集群监控协议服务器，用于提供节点、虚拟机和存储的实时信息，以保持实验室文档的最新状态。

  • by Harryc6
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Harryc6/ProxmoxMCP

使用说明

最后更新日期：2025-11-28

Proxmox MCP集成

概述

此项目为实现只读模型上下文协议（MCP）服务器 Proxmox集群，以便代理可以提取有关节点、访客、用户和用户的实时信息， 以及存储和使用它来保持实验室文件的最新状态。

MCP服务器公开了一小组工具，用于查询Proxmox HTTP API和 返回有关以下内容的结构化数据：

  • 集群节点（名称、CPU/RAM、状态、IP）。
  • LXC容器和VM（位置、类型、HA组）。
  • 存储（本地ZFS tank 池和任何NFS存储）。

建筑

  • MCP服务器：一个小型Node.js CLI(proxmox-mcp-server)这说明了MCP stdin/stdout连接到客户端。
  • Proxmox API：使用专用的只读API令牌通过HTTPS访问 （例如，具有 PVEAuditor 角色）。
  • 客户端配置：MCP感知客户端（例如Codex）生成 MCP服务器按需提供，并通过环境提供Proxmox连接详细信息 变量。

环境变量：

  • PROXMOX_API_URL: https://proxmox-g4:8006
  • PROXMOX_API_TOKEN_ID：令牌ID（例如 root@pam!mcp-docs)
  • PROXMOX_API_TOKEN_SECRET：令牌密钥
  • PROXMOX_TLS_INSECURE：设置为 1 跳过TLS验证（例如， 当使用自签名证书时）。

服务器实现：

  • initialize：协商 protocolVersion 并宣传工具功能。
  • tools/list：返回带有描述和JSON输入的可用工具 模式。
  • tools/call：执行具有结构化参数的命名工具。
  • notifications/initialized：视为通知（无答复）。

工具

当前公开的工具：

  • list_nodes
    • 说明：列出Proxmox节点的基本规格和状态。
    • 支持： GET /cluster/resources?type=node.
  • list_guests
    • 说明：列出VM和LXC，可选择按节点过滤。
    • 支持： GET /cluster/resources?type=vm.
  • list_storage
    • 说明：列出整个集群的存储池。
    • 支持： GET /cluster/resources?type=storage.
  • list_ha_resources
    • 说明：列出HA管理的资源及其组。
    • 支持： GET /cluster/ha/resources.

TODO：添加摘要资源（例如 proxmox://cluster/summary) 它将节点、客户机和存储信息聚合到一个视图中 代理可以进入[[Proxmox Cluster]]和[[网络拓扑]]。

目标和范围

主要目标：

  • 提供只读Proxmox MCP服务器，该服务器可以：
    • 列出集群节点、它们的规格和IP。
    • 列出带节点位置和HA成员资格的LXC和VM。
    • 列出存储池，特别是本地ZFS tank 以及任何NFS存储。
  • 使用MCP输出使[[Proxmox Cluster]]和[[网络拓扑]]保持同步 与实际集群。
  • 在中反映真实的HA复制行为，以及稍后的正确备份例程 [[备份策略操作手册]]。

非目标（目前）：

  • 通过MCP协调工作负载（启动/停止/迁移客户机）。
  • 更改Proxmox配置（创建或删除资源）。
  • 在此保管库中暴露Proxmox的机密或凭据。

关键决策

2025-11-26–只读Proxmox MCP示波器

  • 初始服务器是严格只读的， 访客、存储和HA资源，但不会改变任何东西。
  • 认证使用专用的只读API令牌（例如， PVEAuditor)，不是完整的管理帐户。

2025-11-26–将MCP与实验室通道置于同一位置

  • 短期：为了简单起见，服务器可以在主工作站上运行。
  • 长期：首选位置是LXC/VM内部的专用管理 Proxmox集群，可通过SSH从工作站访问。
  • 客户端配置应同时支持这两种 proxmox-mcp-server 当地和 ssh mcp-mgmt proxmox-mcp-server 对于管理LXC。

配置示例（Codex）

向Codex注册服务器：

codex mcp add proxmox-mcp-server \
  --env PROXMOX_API_URL='https://proxmox-g4:8006' \
  --env PROXMOX_API_TOKEN_ID='root@pam!mcp-docs' \
  --env PROXMOX_API_TOKEN_SECRET='REDACTED' \
  -- node "/.../proxmox-mcp/bin/proxmox-mcp-server.js"

然后从vault根目录启动Codex：

codex -C "/.../Home Vault"

食品法典委员会将：

  • 呼叫 initialize，然后发送 notifications/initialized.
  • 呼叫 tools/list 以发现可用的工具。
  • 使用 tools/call 调用 list_nodes, list_guests, list_storage，或 list_ha_resources.

状态

2025-11-26–现状

  • Proxmox集群拓扑、HA工作负载和存储（本地ZFS tank 和 NAS NFS共享）记录在：
    • [[Proxmox集群]]
    • [[网络拓扑]]
    • [[NAS]]
    • [[备份策略操作手册]]
  • 所需的MCP工具和集成点概述如下：
    • [[实验室项目和TODO]]
    • 此README。
  • Node.js MCP服务器(proxmox-mcp-server)使用工具实现 list_nodes, list_guests, list_storage，以及 list_ha_resources，以及 已经在当地针对实验室Proxmox API进行了烟雾测试。

杰出工作

根据目前的状况：

  • 将MCP服务器移向其首选的长期位置（管理层 LXC/VM），同时通过SSH保持本地运行。
  • 确保此MCP服务器存在专用的只读Proxmox API令牌 并记录在密码管理器中（不在此保险库中）。
  • 记录并规范代理商应如何调用这些工具进行刷新：
    • [[Proxmox集群]]
    • [[网络拓扑]]
    • [[备份策略操作手册]]
  • 捕获MCP客户端配置示例，并可选择一个简短的runbook [[实验室项目和TODO]]下的条目。

开放式问题：

  • 对于Proxmox API（自签名CA），TLS验证应该有多严格 与可信证书相比）。
  • 是否需要按环境配置（例如实验室与未来） 分段）或单个实验室集中配置就足够了。

安全注意事项

  • 使用受限于只读权限的专用API令牌（例如， PVEAuditor)，不是完整的管理帐户。
  • 将机密存储在环境变量或密码管理器中，切勿直接存储 在这个保险库里。
  • 不要在中暴露改变Proxmox状态（启动/停止/销毁）的工具 初始版本。如果以后需要，请将它们保存在单独的仅限管理员的MCP中 配置。

文档集成

Proxmox MCP服务器将主要支持：

  • [[Proxmox Cluster]]：保存节点列表、HA位置和ZFS/NFS存储 细节准确。
  • [[网络拓扑]]：验证节点IP和角色。
  • [[备份策略操作手册]]：反映真正的HA复制和以后的适当 备份NFS共享使用后的备份工作流。

有关剩余工作的项目级跟踪，请参阅上面的“未完成工作”部分。

相关 MCP