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トランスポート。

Related MCP server: ProxmoxMCP

必要な権限

サーバーには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

公開フロー

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

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

14. 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の正当化が必要です。

• このゲートが満たされるまで、タスクはコミット準備完了とは見なされません。

ドキュメント

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

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

• 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を参照してください。