NANDI Proxmox MCP

Proxmoxクラスターを、自動化、監視、制御された実行のための140以上のツールを備えたAI駆動型プラットフォームに変えましょう。

NANDI Servicesが提供する、Proxmox VE用のオープンソースMCPサーバーです。

nandi-proxmox-mcpは、Proxmoxのインベントリ、ライフサイクル、ストレージ、バックアップ、ネットワーク、ファイアウォール、アクセス、監視、SSH診断、および保護されたリモート/コンテナ操作を公開します。本番クラスターに必要な安全性を損なうことはありません。

有効な機能

ノード、クラスター、QEMU、LXC、ストレージ、バックアップ、タスク、ネットワーク、ファイアウォール、プール、アクセス、テンプレート、監視、リモート操作にわたる140以上のツール。
アクセス階層: read-only、read-execute、full。
モジュール分割: PVE_MODULE_MODE=core|advanced。
ツールフィルター: PVE_CATEGORIES、PVE_TOOL_BLACKLIST、PVE_TOOL_WHITELIST。
confirm=trueによる破壊的操作のガードレール。
listNodes、getVMStatus、startVM、stopContainerなどの後方互換性のあるエイリアス。
MCPクライアント用のstdioトランスポート、および制御されたリモートデプロイ用のストリーム可能なHTTPトランスポート。

必要な権限

サーバーには2つの信頼チャネルが必要であり、両方とも意図的に保持されています。

Proxmox APIトークン
- インベントリ、ライフサイクル、構成、管理エンドポイントに使用されます。
- ACLは最小限に抑えてください。実際に有効にするツールに必要なロールのみを付与してください。
ProxmoxホストへのSSHバッチアクセス
- pct exec、バッチSSH診断、コンテナレベルのDocker検査ツールに必要です。
- Proxmox APIのカバー範囲ではホスト側のpctやSSHベースの診断を完全に代替できないため、依然として必要です。

詳細: docs/PERMISSIONS.md

破壊的操作の確認

破壊的とマークされた操作は、呼び出し元がconfirm=trueを送信しない限り実行されません。

例:

VM/コンテナの停止、シャットダウン、再起動、サスペンド、削除、移行、スナップショットのロールバック
クラスターの状態を変更する可能性のあるストレージ/ネットワーク/ファイアウォール/アクセスの書き込み
pve_exec_in_containerなどの高度なリモート実行

確認が欠落している場合、サーバーは構造化されたCONFIRMATION_REQUIREDエラーを返します。この動作は変更されておらず、強化されています。

アクセス階層

read-only
- インベントリ、ステータス、ログ、メトリクス、および非破壊的な診断。
read-execute
- 読み取り専用に加え、選択された実行/ライフサイクルアクション。
full
- 作成、更新、削除、移行、復元、および管理者レベルの操作。

PVE_MODULE_MODE=coreは、コードベースから正規のツールIDの名前を変更したり削除したりすることなく、高度なツールを非表示にします。

ランタイム構成

環境変数

必須:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

オプション:

PROXMOX_PORT デフォルト 8006
PROXMOX_SSH_PORT デフォルト 22
PROXMOX_ALLOW_INSECURE_TLS デフォルト false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

HTTPトランスポート:

MCP_TRANSPORT=stdio|http
MCP_HOST デフォルト 0.0.0.0
MCP_PORT デフォルト 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

ローカル設定ファイル

セットアップにより、.nandi-proxmox-mcp/config.jsonおよび.vscode/mcp.jsonが書き込まれます。

設定ローダーは以下を拒否するようになりました:

空または不正な形式の設定パス
サイズ超過の設定ファイル
設定パス内の制御文字

クイックスタート

ガイド付きセットアップ:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

環境変数を使用した直接実行:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

セキュリティモデルと残存リスク

このMCPサーバーは実際のProxmoxインフラストラクチャを操作するものであり、サンドボックス環境ではありません。

信頼の前提条件

サーバーは信頼された環境にデプロイされている
許可されたオペレーターのみがアクセスできる
ネットワーク露出が制御されている（公開されていない）
資格情報が安全に管理されている

残存リスク

以下のリスクはシステム設計に固有のものです:

特権操作 フルアクセス階層およびコンテナ実行機能は、破壊的またはシステムレベルのアクションを実行できます。
SSH実行境界 リモートコマンド実行はSSHに依存しており、ターゲットシステムのセキュリティ体制を継承します。
オプションの非セキュアTLSモード 有効にすると（PROXMOX_ALLOW_INSECURE_TLS=true）、TLS証明書の検証がバイパスされ、MITM攻撃に対して接続が露出する可能性があります。ラボでの使用のみを目的としています。
外部依存関係の同期 パッケージの配布およびリストの可視性は、npm、MCPレジストリ、およびマーケットプレイスの伝播タイミングに依存します。

セキュリティ責任

ユーザーは以下の責任を負います:

信頼されたオペレーターのみにアクセスを制限すること
最小権限のAPIトークンとSSHキーを使用すること
本番環境で非セキュアなTLSを避けること
基盤となるインフラストラクチャを適切に保護すること

実装された安全制御

アクセス階層（read-only、read-execute、full）
破壊的操作に対する確認の必須化
入力検証とコマンドの強化
レート制限とリクエスト検証

HTTPの強化

MCP_TRANSPORT=httpが有効な場合、サーバーは以下を適用します:

ワイルドカードバインド保護を含むホスト許可リストの強制
Originヘッダーを送信するリクエストに対するオリジン検証
明示的なボディサイズ制限とサニタイズされた413レスポンス
/mcpに対するレート制限
リクエスト/ヘッダー/キープアライブのタイムアウト
X-Content-Type-Options: nosniff
Cache-Control: no-store
スタックトレースを含まないサニタイズされたエラーペイロード

ヘルス/レディネスエンドポイント:

GET /health
GET /ready
POST /mcp

SSHおよびコマンド実行の強化

機能は変更されていませんが、実行パスはより厳格になっています:

ローカルコマンド実行は引き続きspawn(..., { shell: false })を使用します
SSHホスト/ユーザー値はCLIオプションを不正に含めることはできません
SSHはBatchMode、IdentitiesOnly、公開鍵認証、および明示的な接続生存制御を使用します
出力バッファは、無制限のメモリ増加を防ぐために制限されています
dockerLogsInContainerは、生のユーザー入力を補間する代わりに、コンテナ名を検証しシェルエスケープするようになりました
任意のコンテナコマンド実行は、確認が必要な既存の破壊的フローpve_exec_in_containerを通じてのみ利用可能です

セキュリティ体制

リポジトリ内の緩和策:

重要な推移的パッケージに対する固定された直接依存関係バージョンとnpm overrides
npm/パッケージスキャナー用の検証可能なパッケージメタデータとリポジトリリンク
npm、レジストリ、マーケットプレイスアーティファクトの記述子/バージョン同期検証
ログ内のトークン/ヘッダー/パスワードのような値の編集
クライアントに返されるスタックトレースやシークレットの排除
lint、型チェック、ビルド、テスト、メタデータ検証、記述子同期、npm pack --dry-run、および監査のためのCIゲート

脅威モデルと残存リスク: docs/THREAT_MODEL.md

公開フロー

リリース順序は厳格です:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

タグベースのrelease.ymlは、まずnpmを公開し、その後にのみMCPレジストリ記述子を公開することで、同じバージョンでのnpm/レジストリの乖離を防ぎます。

手動フォールバックとトラブルシューティング: docs/RELEASE.md

開発

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

ドキュメント保守ポリシー

このリポジトリは、コミット前のドキュメント同期ゲートを強制します。

change、fix、またはrefactorをクローズする前に、README.md、AGENTS.md、およびCONTRIBUTING.mdを更新する必要があるかどうかを評価してください。
ドキュメントが動作やプロセスへの影響に関連している場合は、同じ変更セットで更新する必要があります。
更新が不要な場合は、明示的なno-doc-changeの正当化が必要です。
このゲートが満たされるまで、タスクはコミット準備完了とは見なされません。

ドキュメント

レジストリとマーケットプレイス

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
MCPレジストリ: https://registry.modelcontextprotocol.io/
MCPマーケットプレイスリスト: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

ライセンス

MIT。LICENSEを参照してください。

nandi-proxmox-mcp