nandi-proxmox-mcp

NANDI Proxmox MCP

140 以上のツールで自動化、監視、制御された実行を可能にし、Proxmox クラスターを 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 トランスポートと、制御されたリモートデプロイ向けの Streamable 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 エラーを返します。この動作は変更されておらず、より強化されています。

人による承認

confirm=true はあなたではなく、エージェントによって設定されます。拒否された理由を読んだモデルは、フラグを設定して再試行できるため、このチェック単独では慎重なエージェントではなく、誤操作を防ぐだけです。また、あなたに確認を求めることもありません。

そのため、確認を必要とする47個のツールは、クライアントにも人による確認が必要であると通知されます。

"_meta": { "anthropic/requiresUserInteraction": true }

Claude Code 2.1.199以降では、このようにマークされたツールは、auto モードや bypassPermissions モードを含め、呼び出しのたびにプロンプトを表示します。また、allow ルールや allow を返す PreToolUse フックによる事前承認はできません。--permission-prompt-tool のもとでは、自動承認は拒否に変換されます。また、Remote Control はワンタップ承認を表示せず、通常のプロンプトを表示します。操作を承認したのは、回答したオペレーターです。

ただし、ドキュメントの記述ではなく、2.1.229で確認した注意点があります。ドキュメントには、フラグが設定されたツールにはその選択肢がないと書かれていますが、プロンプトには引き続き 「はい。今後は確認しない」 が表示されます。これを選択すると allow ルールが書き込まれますが、ゲートは解除されず、次の呼び出しでも再びプロンプトが表示されます。つまり、動作は正しく、ボタンの表示だけが誤解を招きます。ボタンがないことをガードが有効である証拠と考えないでください。ゲート対象のツールを2回呼び出して確認してください。

ゲストの起動と再開は、意図的に対象外としています。これらは何かを破壊せずに状態を変更するものであり、敬遠されるガードは迂回されるからです。

setup はさらに、一致する permissions.ask ルールを .claude/settings.json に書き込み、アノテーションより前の Claude Code バージョンにも対応します。ルールは deny、ask、allow の順に評価され、最初に一致したルールが適用されるため、bypassPermissions や、その後の「はい。今後は確認しない」の選択後も ask ルールが適用されます。setup ではなく手動で設定したインストールの場合は、次のようにします。

nandi-proxmox-mcp harden              # every configured instance
nandi-proxmox-mcp harden --name lab   # just one

どちらの仕組みも Claude Code 固有です。他のクライアントでは、ガードとなるのは confirm=true とアクセス層です。そのため、そこで使用する層は慎重に選んでください。

アクセス層

• 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

ローカル設定ファイル

セットアップでは、設定した Proxmox ごとに認証情報ファイル .nandi-proxmox-mcp/<instance>.json を作成し、指定された各クライアント設定に登録エントリーを追加します。デフォルトでは、Claude Code 用の .mcp.json と VS Code 用の .vscode/mcp.json の両方が対象です。

トークンを保持するのは認証情報ファイルだけで、そのファイルは gitignore に登録されています。NANDI_PROXMOX_CONFIG が設定されていない場合、サーバーが設定ファイルを検出します。設定済みのインスタンスが1つなら自動的に使用し、複数ある場合は推測せず、インスタンス名を示すエラーになります。

設定ローダーは、次の設定を拒否するようになりました。

• 空の設定パス、または形式が不正な設定パス
• サイズが大きすぎる設定ファイル
• 設定パス内の制御文字

クイックスタート

MCP を使ったことがありませんか？ まず docs/EMPEZAR.md をご覧ください。MCP の予備知識がない方向けの ステップバイステップガイド（スペイン語）で、つまずく方が多い Proxmox トークンの 作成方法も説明しています。

まず、ご自身の Proxmox 用の API トークンが必要です。以下を実行すると、Proxmox シェルに 貼り付けて使える作成コマンドが表示されます。どこにも接続しません。

npx nandi-proxmox-mcp bootstrap --tier read-only

続いて、ガイドに沿ってセットアップします。デフォルトでは、Claude Code （.mcp.json）と VS Code（.vscode/mcp.json）用の設定を書き込みます。いずれかのファイルが すでに存在する場合は、既存の内容にマージします。

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

まずは --access-tier read-only を指定してください。サーバーの組み込みのデフォルトは full で、 任意のコマンド実行を含む、すべての破壊的なツールが公開されます。このフラグを指定すると、 クライアント設定にアクセス層が明示的に書き込まれるため、選択内容が暗黙的ではなく明確になります。 セットアップを信頼できるようになったら、アクセス層を引き上げてください。

特定のクライアントを選択するか、ほかの MCP クライアント向けの設定ブロックを出力できます。

npx nandi-proxmox-mcp setup --clients claude-code
npx nandi-proxmox-mcp setup --print-config          # writes nothing, safe to pipe

.mcp.json に含まれるのは設定パスとポリシー設定のみなので、安全にコミットして共有できます。 API トークンは .nandi-proxmox-mcp/config.json に保存されます。このファイルは gitignore の対象です。

環境変数を使って直接実行する場合：

$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 Registry、マーケットプレイスへの反映にかかる時間に左右されます。

セキュリティに関する責任

ユーザーには以下の責任があります。

• 信頼できるオペレーターのみにアクセスを制限する
• 最小権限の API トークンと SSH キーを使用する
• 本番環境では安全でない TLS を使用しない
• 基盤となるインフラストラクチャを適切に保護する

実装済みの安全対策

• アクセス層（読み取り専用、読み取り・実行、フル）
• 破壊的な操作には確認が必要
• 同じ操作には人による承認が必要です。詳しくは人による承認をご覧ください。
• 入力の検証とコマンドの強化
• レート制限とリクエストの検証

HTTP のセキュリティ強化

HTTP トランスポートでは認証を行いません。 POST /mcp には、Bearer トークン、API キー、クライアント証明書のチェックはありません。以下の対策はネットワークレベルのものに限られます。また、MCP_HOST のデフォルト値は 0.0.0.0 で、許可ホストリストには、設定済みの Proxmox ホストと SSH ホストが含まれます。ポートに接続でき、一致する Host ヘッダーを送信できる人は誰でも、登録済みのツールをすべて利用できます。デフォルトの PVE_ACCESS_TIER=full では、破壊的なツールや任意のコマンド実行も含まれます。

MCP_TRANSPORT=http を有効にするのは、信頼できるネットワーク上、認証を行うリバースプロキシの背後、または MCP_HOST を使って 127.0.0.1 にバインドする場合に限ってください。デフォルトの stdio トランスポートにはネットワーク経由の接続面がないため、影響を受けません。

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

• ワイルドカードバインドの保護を含む、ホスト許可リストの適用
• Origin ヘッダーを含むリクエストのオリジン検証
• 明示的なリクエストボディサイズ制限と、サニタイズされた 413 レスポンス
• /mcp のレート制限
• リクエスト、ヘッダー、Keep-Alive のタイムアウト
• 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

公開フロー

リリースは自動です。 main へのプッシュで auto-release.yml が実行され、直近の v* タグ以降の Conventional Commit の件名からバージョンの引き上げレベルを読み取り、バージョンを含むすべてのファイルに新しいバージョンを書き込み、chore(release): vX.Y.Z をコミットしてタグをプッシュします。このタグによって release.yml と、以下の公開処理が開始されます。

コミット	引き上げ
feat:	マイナー
fix:, perf:, revert:	パッチ
feat!: または BREAKING CHANGE: フッター	メジャー — 厳密な SemVer に従うため、0.x は 1.0.0 になります
chore:, docs:, test:, ci:, build:, style:, refactor:	公開されません

リリース対象がないプッシュは成功として完了し、スキップしたコミットの一覧を表示します。dry_run: true を指定してワークフローを手動実行すると、公開せずにバージョンと差分を確認できます。

バージョンは8か所に記載されています。マニフェスト、2つのレジストリ記述子、マーケットプレイスのプラグイン、ドキュメント内の2つの例、TypeScript のリテラル2つです。scripts/set-version.mjs がそれらすべてに書き込み、scripts/validate-package-metadata.mjs がそれらすべてを検証します。9か所目を追加する場合は、両方を編集してください。バリデーターが無視するファイルに書き込むようにした結果、0.3.1 が 0.2.4 として告知されてリリースされました。

タグ作成後のリリース順序は厳守してください。

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 Registry の記述子を公開します。これにより、同じバージョンで npm とレジストリの内容が食い違うのを防ぎます。

リリースが途中で失敗した場合は、手動で完了させるのではなく再実行してください — gh workflow run release.yml --ref vX.Y.Z。各公開ステップは最初に公開先を確認し、すでに公開済みのものはスキップするため、再実行では未完了の処理だけが完了します。タグではない ref、および package.json のバージョンと一致しないタグは、ジョブによって拒否されます。

手動での代替手順とトラブルシューティング：docs/RELEASE.md

開発

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

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

このリポジトリでは、Git フックではなくレビューで徹底するドキュメント同期ポリシーを採用しています。

pre-commit フックはありません。自動化されている唯一のゲートは CI (.github/workflows/ci.yml) にあり、docs/TOOLS.md を再生成して、 差分があればビルドを失敗させます。また、リポジトリ内の .git/hooks/pre-commit は、core.hooksPath が別の場所に設定されたマシンでは 実行されません。この設定は一般的です。

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

ドキュメント

• docs/EMPEZAR.md — MCP サーバーを初めて使う方は、ここから始めてください
• docs/CLAUDE_CODE_SETUP.md
• 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 Registry：https://registry.modelcontextprotocol.io/
• MCP Marketplace の掲載ページ：https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

ライセンス

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