Proxmox Monitoring MCP Server

只读监控与配置审计，用于 Proxmox IaaS 集群，通过 MCP 提供给 Claude。本地通过 stdio 运行；此包中没有任何写入路径（proxmox_mcp/client.py 仅实现 GET），并且 API 令牌使用 PVEAuditor 角色，因此 Proxmox 本身会强制只读。

1. 在 Proxmox 上创建 API 令牌（一次性操作，在任意节点以 root 身份执行）

pveum user add claude-monitor@pve --comment "Read-only MCP monitoring"
pveum acl modify / --users claude-monitor@pve --roles PVEAuditor
pveum user token add claude-monitor@pve mcp --privsep 1
pveum acl modify / --tokens 'claude-monitor@pve!mcp' --roles PVEAuditor

token add 命令只打印一次密钥——请立即复制。在启用权限分离（--privsep 1）的情况下，令牌的有效权限是用户 ACL 与令牌 ACL 的交集，这就是为什么必须将 PVEAuditor 授予两者（第四条命令是大家最容易忘记的）。

GUI 等效操作：数据中心 → 权限 → 用户 → 添加；数据中心 → 权限 → API 令牌 → 添加；然后数据中心 → 权限 → 添加 → 在路径 / 上分别添加用户权限和API 令牌权限，角色为 PVEAuditor，并开启传播（Propagate）。

Related MCP server: proxmox-mcp

2. 配置并安装（本机）

cd <your-workspace>/proxmox-mcp
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
cp .env.example .env    # then fill in PROXMOX_HOST / TOKEN_ID / TOKEN_SECRET

3. 在 Claude Code 中注册

claude mcp add proxmox --scope user -- <your-workspace>/proxmox-mcp/.venv/Scripts/python.exe <your-workspace>/proxmox-mcp/run_server.py

工具

config_audit 检查项：备份覆盖率、过期快照、存储 >85%、节点内存 >90%、内存超分 >1.5x、CPU 超分 >4x、各节点间 PVE 版本漂移、默认的 kvm64 CPU 类型、guest agent 被禁用、IDE 总线上的磁盘，以及最近 48 小时内失败的任务。阈值可在 .env 中调整。

服务器自带三个 MCP 提示词（可在 claude.ai 的“Add from proxmox-monitor”下看到）：Cluster Config Audit、Cluster Health Brief、Backup Coverage Check。

向团队提供服务（远程，Entra 认证）

该服务器支持双传输。MCP_TRANSPORT=stdio（默认）用于本地 Claude Code；MCP_TRANSPORT=http 在资源服务器模式下提供可流式 HTTP，并使用 Microsoft Entra ID 认证，详见 ~/.claude/context/mcp-server-playbook.md。

• Entra： scripts/setup_entra_app.ps1 创建并配置应用、access_as_user 作用域、两个 Claude 重定向 URI、v2 令牌、客户端密钥，以及带成员的 Proxmox-MCP-Users 安全组。先使用 -ResolveOnly 运行，以检查队友列表能否解析。详细内容与手动回退方案：docs/ENTRA_SETUP_CHECKLIST.md。

• 部署： 在 10.0.0.10 上使用主机端口 8119，公共主机名 proxmox-mcp.example.com。步骤、堆栈变量和 NPM 代理主机配置：PORTAINER_DEPLOY.md。

部署目前受阻，直到 docker 主机的 default-address-pools 维护完成为止——它的网络数已达到 31/31，因此任何新堆栈在创建时都会失败。Entra 注册现在就可以完成；与此同时，stdio 服务器会继续正常工作。

测试

<your-workspace>/proxmox-mcp/.venv/Scripts/python.exe -m pytest tests -q

它们无需连接 Proxmox。它们断言每个工具和提示词都已注册，每个提示词都会指明自己的连接器（在十几个已连接的连接器之间词汇表会发生冲突），ProxmoxClient 没有新增任何修改状态的方法，并且认证在配置不完整时会拒绝启动。