Skip to main content
Glama
deenesjakoruzh
dallaswk

proxmox-ai

by dallaswk
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

proxmox-ai

一个 MCP 服务器，让 AI 代理能够用自然语言管理 Proxmox VE，绝不授予超出严格必要的权限。

"¿Qué contenedores están ejecutándose?"        → responde
"¿Cuál está consumiendo más RAM?"              → responde
"Reinicia el CT 105"                           → propone, espera confirmación, ejecuta
"Haz rollback del snapshot pre-update"         → exige una frase literal del humano
"Borra el CT 105"                              → no existe esa herramienta

设计源于一个理念：模型提议，策略引擎决定，审计日志记录。

状态

第 1 阶段（只读）已实现并测试。第 2 至第 5 阶段已实现，但默认禁用：通过环境变量逐个启用，并且每个阶段还需要在 Proxmox 的 ACL 中具有相应权限。参见 docs/roadmap.md。

MCP 工具

27

测试

229 (pytest)

依赖

mcp, httpx

Python

≥ 3.11

快速安装

在 Proxmox 节点上，创建专用用户和令牌：

./scripts/setup-proxmox-user.sh

复制令牌密钥：Proxmox 不会再次显示它。

在 MCP 所在的容器中（创建方法见 docs/instalacion.md）：

git clone https://github.com/dallaswk/proxmox-ai.git
cd proxmox-ai
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env && chmod 600 .env
$EDITOR .env          # PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET

检查它能否启动并看到基础设施：

set -a && . ./.env && set +a
proxmox-ai            # habla MCP por stdin/stdout; Ctrl-C para salir

将它连接到你的 MCP 客户端（Claude Desktop、Claude Code 等）：

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

安全机制的工作原理

四个独立的层。每一层单独都有效：

1. Proxmox 的 ACL。 这是真正的边界。令牌是一个专用用户，使用 --privsep 1，绝不是 root@pam，在第 1 阶段只拥有 PVEAuditor。一个不能删除 VM 的令牌，即使所有其他防护都失效，也无法删除它。

2. 能力标志。 PROXMOX_AI_READ_ONLY=true 会阻止任何写入操作，无论其他配置如何。每个阶段都有自己的标志，不可逆操作还需要额外的标志。

3. 两步确认。 调用写入工具时如果没有 confirm_token，不会碰任何东西：它会返回一个计划和一个与该确切操作绑定的单次使用令牌。人在两次调用之间会看到计划。对于不可逆操作，还必须发送一个逐字短语（CONFIRMO ROLLBACK SNAPSHOT 105）；仅仅一个“是”是不够的。

4. 没有任意的 shell。 不存在 execute_any_command。在客户机内部执行的命令需要通过 argv 白名单，前面还有两个黑名单——二进制（rm、dd、bash……）和破坏性选项——以及 shell 元字符的拒绝。选项黑名单的存在是因为一个看似只读的二进制可能有一个并非只读的标志：journalctl -u nginx --vacuum-time=1s 会删除已归档的日志。参数还会用 shlex.quote 进行转义，因为 ssh host cmd 总是会被远程 shell 重新解释。

而在这一切之下，是一个仅追加的 JSONL 日志，记录每一次尝试——包括被拒绝的——并且不包含任何秘密。

这无法解决的问题： MCP 服务器无法区分“人是说了同意”和“模型决定继续”。两步确认保证不会因为一次调用而产生不可逆的副作用，并留下一切痕迹，但硬性保证仍来自 ACL。在 docs/modelo-de-seguridad.md 中有不加修饰的说明。

工具

第 1 阶段 — 只读（默认启用，只需要 PVEAuditor）

工具

用途

pve_policy_status

当前允许什么

pve_list_nodes

节点及其 CPU、RAM 和根磁盘

pve_list_guests

LXC 和 VM 及其消耗；VMID 来自这里

pve_top_consumers

按 RAM、CPU 或磁盘排名

pve_guest_status

客户机的详细状态

pve_guest_config

配置：核心、内存、磁盘、网络

pve_guest_metrics

RRD 历史数据：区分瞬时峰值与持续问题

pve_storage_status

可用空间，85% 和 92% 时发出警报

pve_recent_tasks

最近的任务以及哪些失败

pve_task_log

某个任务的完整日志

pve_list_snapshots

某个客户机的快照

pve_list_backups

可用的备份

pve_health_report

完整检查：节点、客户机、存储、任务

第 2 阶段 — 电源管理（PROXMOX_AI_ENABLE_POWER，权限：VM.PowerMgmt）

pve_guest_power — start、shutdown、reboot、stop。必须确认。

第 3 阶段 — 快照（PROXMOX_AI_ENABLE_SNAPSHOT，权限：VM.Snapshot）

pve_create_snapshot（级别 1）· pve_rollback_snapshot 和 pve_delete_snapshot（级别 2：逐字短语 + PROXMOX_AI_ENABLE_DESTRUCTIVE）

第 4 阶段 — 备份（PROXMOX_AI_ENABLE_BACKUP，权限：VM.Backup）

pve_create_backup — 级别 1。故意未实现恢复功能：它是 Proxmox 中破坏性最强的操作。参见 docs/modelo-de-seguridad.md。

第 5 阶段 — 客户机内部诊断（PROXMOX_AI_ENABLE_GUEST_EXEC）

工具

用途

guest_list_allowed_commands

代理可以执行什么

guest_check_service

nginx 是否在运行？

guest_read_logs

journalctl，可选择仅显示错误

guest_resources

从内部看到的 df/free/uptime

guest_docker_ps · guest_docker_logs

Docker 容器的状态和日志

guest_run_command

白名单中的一条命令

guest_diagnose_web

对 Web 技术栈的完整诊断

guest_restart_service

重启服务。级别 1

两步确认的真实示例

Usuario:  Reinicia el CT 105.

Agente:   [pve_guest_power vmid=105 operation=reboot]
          → confirmation_required
            "REBOOT CT 105 (web-production) on node pve1 — will request a
             clean reboot via the guest OS."
            nothing_has_changed: true
            confirm_token: "kJ8x...b2"

          Voy a reiniciar el CT 105 (web-production) en el nodo pve1.
          Es un reinicio limpio a través del sistema operativo. ¿Confirmas?

Usuario:  Sí.

Agente:   [pve_guest_power vmid=105 operation=reboot confirm_token="kJ8x...b2"]
          → status: completed

          Reiniciado. La tarea terminó con estado OK.

如果代理试图对 CT 101 使用同一个令牌，或执行 stop 而不是 reboot，引擎会拒绝：该令牌通过 HMAC 与确切的操作、客户机和参数绑定。

开发

pip install -e ".[dev]"
pytest                    # 229 tests, sin red ni Proxmox real
ruff check src tests

测试使用 httpx.MockTransport 和一个模拟集群（1 个节点、2 个 CT、1 个 VM、2 个存储）。开发时不需要 Proxmox。

文档

许可证

MIT

This server cannot be installed

-
license - not tested
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

  • mcp-aichat

    MCP server for AI dialogue using various LLM models via AceDataCloud

  • gainium-mcp

    MCP server for Gainium — manage trading bots, deals, and balances via AI assistants

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dallaswk/proxmox-ai'

If you have feedback or need assistance with the MCP directory API, please join our Discord server