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は実装済みだがデフォルトでは無効：環境変数で1つずつ有効にでき、それぞれにProxmox ACLの特権も必要。 docs/roadmap.md を参照。

クイックインストール

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"
      }
    }
  }
}

セキュリティの仕組み

独立した4つのレイヤー。それぞれ単独で有効。

1. Proxmox ACL。 これが本当の境界。トークンは --privsep 1 の専用ユーザーで、決して root@pam ではなく、フェーズ1では PVEAuditor のみ。VMを削除できないトークンは、他のすべてが失敗しても削除できない。

2. 機能フラグ。 PROXMOX_AI_READ_ONLY=true は、他の設定に関係なくすべての書き込みをブロックする。各フェーズに独自のフラグがあり、不可逆的な操作には追加のフラグが必要。

3. 2段階確認。 confirm_token なしで呼び出された書き込みツールは何も変更しない：プランと、その正確なアクションに紐づいたワンタイムトークンを返す。人間は2回の呼び出しの間にプランを見る。不可逆的な操作には、さらにリテラルなフレーズ（CONFIRMO ROLLBACK SNAPSHOT 105）を送信する必要がある。「はい」では不十分。

4. 任意のシェルなし。 execute_any_command はない。ゲスト内のコマンドはargvのホワイトリストを通過し、その前に2つのブラックリスト（バイナリ（rm、dd、bash…）と破壊的なオプション）があり、シェルのメタ文字は拒否される。オプションのブラックリストがあるのは、読み取り専用に見えるバイナリにも破壊的なフラグがあるため：journalctl -u nginx --vacuum-time=1s はアーカイブされたログを削除する。引数はさらに shlex.quote でエスケープされる。ssh host cmd は常にリモートシェルで再解釈されるからだ。

そしてその下に、すべての試行（拒否されたものも含む）を記録し、シークレットを一切含まない追記専用のJSONLログがある。

これが解決しないこと： MCPサーバーは「人間が同意した」と「モデルが続行を決定した」を区別できない。2段階確認は、単一の呼び出しの副作用として不可逆的なことが起こらないことを保証し、すべての痕跡を残すが、永続的な保証はACLである。これは docs/modelo-de-seguridad.md で飾り気なく説明されている。

ツール

フェーズ1 — 読み取り（デフォルトで有効、PVEAuditor のみ必要）

フェーズ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）

2段階確認の実際の例

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に、または reboot の代わりに stop に使おうとした場合、エンジンは拒否する：トークンは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は不要。

ドキュメント

• docs/instalacion.md — ステップバイステップのインストール

• docs/modelo-de-seguridad.md — 脅威と限界

• docs/roadmap.md — 7つのフェーズ、チェックリスト付き

• docs/especificacion-original.md — 出発点のドキュメント

ライセンス

MIT