Proxmox VE

---

「今日、データベース VM の動作が遅いのはなぜですか？」 pve2 上の VM 101（db）は 09:00 以降、CPU 使用率が平均 94% で、同じ時間帯に pve2 の IO 待機率も 30% を超えています。そのディスクは local-lvm 上にあり、容量の 91% が使用されています。また、昨夜から同じディスクへのバックアップタスクがまだ実行中です。バックアップタスクのログを表示するか、空きメモリが 40 GiB ある pve1 への VM の移行を計画しましょうか？

クラスターについて、普段の言葉で質問できます。アシスタントは300以上のツールから適切なものを選んで情報を調べ、許可されていれば変更も実行します。たとえば、次のように質問できます。

• 🩺 「クラスターのヘルスチェックをしてください。」
• 📈 「最も多くのメモリを使っている VM と、最も余裕のあるノードはどれですか？」
• 💾 「バックアップされていないゲストはどれですか？昨夜のバックアップは成功しましたか？」
• 🧹 「1か月以上前のスナップショットを探してください。」
• 🔐 「ユーザー、API トークン、権限を確認して、リスクのあるものがないか調べてください。」
• 🚀 「Debian テンプレートをクローンして、VLAN 20 上に RAM 4 GB の web-02 という新しい VM を作成してください。」

特長

• 🐳 Docker を第一に設計。 linux/amd64 と linux/arm64 向けの、小さな distroless イメージ（ghcr.io/mattoddie/proxmox-mcp）を1つ用意しています。長時間稼働するサービス向けの Streamable HTTP、または docker run -i 向けの stdio で動作します。
• 🖱️ ワンクリックで Claude Desktop にインストール。 各リリースには、macOS、Windows、Linux 用の MCP Bundle（.mcpb）が含まれています。開いて設定フォームに入力するだけで使えます。Docker は不要です。
• 🛡️ デフォルトで安全。 書き込みを有効にしない限り、サーバーは読み取り専用です。削除には2つ目のスイッチ、ゲスト内でのコマンド実行には3つ目のスイッチが必要です。許可されていないツールは登録されず、破壊的なツールにはラベルが付くため、MCP クライアントは実行前に確認を求めます。すべての変更は dry_run で事前確認でき、監査ログに記録されます。また、パスワードやキーは出力から除外されます。
• 🧰 幅広い機能。 クラスター、ノード、VM、コンテナー、ゲストエージェント、スナップショット、ストレージ、バックアップ、タスク、アクセス制御、ファイアウォール、HA、SDN、Ceph、プール、レプリケーション、通知、ハードウェア、Raw API ツールの19のツールセットに対応しています。
• ⏱️ タスクに対応。 起動、クローン、移行、バックアップなどの時間がかかる操作は、Proxmox のタスクとして実行されます。ツールはタスクの完了を待って、タスクログの末尾とともに結果を報告するか、後から状況を確認できるようタスク ID を返します。
• 🎯 VMID で指定。 VM 100 について質問すると、サーバーがその VM の所在ノードを特定します。シングルノード構成では、ノード名を指定する必要はありません。
• 🎛️ 調整可能。 必要なツールセットだけを公開できます。また、一覧取得ツールでは search、fields、limit を指定できるため、モデルのコンテキストを小さく保ち、必要な情報に集中できます。
• 🔑 最小権限。 Proxmox 独自のロールと ACL で範囲を限定した専用の API トークンを使うことで、Proxmox 側でもアクセス範囲が制限されます。
• 🧪 テスト済み。 テストスイートは、すべてのビルドでモックの Proxmox API を使って実行されます。

クイックスタート

Docker、Proxmox VE 8 または 9 のサーバーかクラスター、および Claude Code などの MCP クライアントが必要です。

1. API トークンを作成します。 いずれかのノードで root として、読み取り専用のユーザーとトークンを作成します。

pveum user add mcp@pve --comment "proxmox-mcp"
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve mcp --privsep 0

出力されたトークンシークレットをコピーしてください。後から再表示することはできません。はじめにでは、変更を加えられるトークンなど、各種オプションについて説明しています。

2. サーバーを起動します。

mkdir proxmox-mcp && cd proxmox-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/example.env -o .env
# Edit .env: set PROXMOX_URL, PROXMOX_TOKEN_ID (mcp@pve!mcp), PROXMOX_TOKEN_SECRET,
# a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`) and how to check the
# Proxmox certificate (required for https): PROXMOX_TLS_FINGERPRINT (recommended; the
# SHA-256 fingerprint from Node > System > Certificates), or PROXMOX_VERIFY_SSL=false
docker compose up -d

3. アシスタントを接続します。

claude mcp add --transport http proxmox http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Claude Code で「Proxmox クラスターの状態はどうですか？」と尋ねてみましょう。

Claude Desktop をお使いですか？ Docker は不要です。最新リリースからお使いのコンピューター用の .mcpb バンドルをダウンロードして開き、設定フォームに入力してください。Claude Desktopをご覧ください。

VS Code、Cursor、または Codex をお使いですか？MCP クライアントの接続をご覧ください。サービスを実行したくない場合は、docker run -i を使ったstdio モードをご利用ください。

proxmox-mcp は MCP Registry に io.github.mattoddie/proxmox-mcp として登録されています。そのため、レジストリを参照できるクライアントからインストールし（stdio 経由の Docker イメージ、または Claude Desktop バンドルとして）、設定を尋ねることができます。

変更を有効にする

初期状態では、アシスタントは情報を確認できますが、変更はできません。変更を許可するには、これらを .env に追加し、docker compose up -d を実行してください。

PROXMOX_ALLOW_WRITES=true    # start/stop guests, create, clone, migrate, reconfigure, snapshot, back up…
PROXMOX_ALLOW_DELETES=true   # also allow deleting guests, snapshots, backups and configuration (needs writes)
PROXMOX_ALLOW_EXEC=true      # also allow commands and file access inside VMs via the guest agent (needs writes)
PROXMOX_TOOLSETS=cluster,nodes,vms,containers,snapshots,backup,tasks   # optional: expose fewer tools
PROXMOX_AUDIT_LOG=/audit/audit.jsonl    # optional: log every change as JSON (mount ./audit; see compose.yaml)

変更を加える各ツールには dry_run があるため、変更を実行する前に、アシスタントにその内容を表示させることができます。トークンにも対応する Proxmox 権限が必要です。本番クラスターで書き込みを有効にする前に、セキュリティをお読みください。

できること

ツールセット	対応内容
cluster	クラスターの概要、ノードとゲストの概況、データセンターのオプション、corosync 設定、メトリックサーバー、一括ゲスト操作
nodes	ノードの状態と統計情報、サービス、ネットワークインターフェース、DNS、時刻、アップデートとリポジトリ、サブスクリプション、証明書と ACME、ログ、ノードの電源
vms	QEMU VM：状態、設定、電源、作成、クローン、ディスク、移行、テンプレート、cloud-init、統計情報
containers	LXC コンテナー：状態、設定、電源、作成、クローン、ボリューム、移行、テンプレート、インターフェース、統計情報
agent	QEMU ゲストエージェント：OS、ネットワーク、ファイルシステムの情報、フリーズ／トリム、および（exec を使った）コマンド実行とファイルアクセス
snapshots	VM とコンテナーのスナップショット：一覧表示、作成、ロールバック、削除、クラスター全体の古いスナップショットの表示
storage	ストレージの定義と使用状況、ボリューム、ISO とテンプレートのダウンロード、物理ディスク、SMART、ZFS、LVM
backup	vzdump バックアップジョブ、アドホックバックアップ、バックアップ一覧表示、復元、プルーニング、バックアップのないゲスト
tasks	Proxmox タスク：一覧表示、詳細確認、ログの読み取り、待機と停止
access	ユーザー、グループ、ロール、ACL、API トークン、レルム、有効な権限、二要素認証
firewall	データセンター、ノード、ゲストレベルのルール、オプション、エイリアス、IP セット、セキュリティグループ、ファイアウォールログ
ha	高可用性の状態、リソース、グループ、ルール
sdn	SDN ゾーン、VNet、サブネット、コントローラー、IPAM と DNS、保留中の変更の適用
ceph	Ceph の健全性、OSD、プール、モニター、マネージャー、メタデータサーバー、CephFS、フラグ
pools	リソースプールとそのメンバー
replication	ストレージレプリケーションジョブ、状態、ログ
notifications	通知ターゲットとマッチャー
hardware	PCI と USB デバイス、仲介デバイス、リソースマッピング、CPU モデル
raw	任意の Proxmox API パスを呼び出すための手段です。PROXMOX_TOOLSETS に raw（例：all,raw）が指定されていない限り無効です

すべてのツールと引数については、**ツールリファレンス**をご覧ください。cluster_health_check、backup_audit、troubleshoot_guest などのすぐに使えるプロンプトは、一般的な作業向けにツールを連携させます。

ドキュメント

ドキュメントは検索機能付きで、proxmox-mcp.mattoddie.dev/docs にも公開されています。

🚀 はじめに	API トークンの取得から最初の質問まで、手順に沿ったセットアップ
🔌 MCP クライアントの接続	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio モード
⚙️ 設定	すべての環境変数、Docker シークレット、ツールセット
🐳 デプロイ	Compose、イメージタグ、アップグレード、TLS リバースプロキシ、セキュリティ強化
💬 proxmox-mcp の使用	会話例、プロンプト、タスク、変更とシークレットの動作
🧰 ツールリファレンス	コードから生成された、すべてのツールとプロンプト
🛡️ セキュリティ	脅威モデル、最小権限トークン、安全な書き込み設定
📡 互換性	対応する Proxmox VE バージョン、Ceph、PBS、既知の制限
🩹 トラブルシューティング	よくあるエラーとその解決方法
🛠️ 開発	アーキテクチャ、ツールの追加、テスト

スマートフォンをお使いですか？同じ作者によるiPhone向けの無料Proxmox VEアプリ、Proxlyを使えば、ノード、VM、コンテナの監視、ゲストの起動と停止、スナップショットとバックアップの作成ができ、ノートパソコンを使う必要がありません。

コントリビューション

バグ報告、クラスターからの互換性レポート、ドキュメント、新しいツールなど、どのようなコントリビューションも歓迎します。コントリビューションガイドを読んで始めてください。また、行動規範に従ってください。脆弱性を報告する場合は、セキュリティポリシーをご覧ください。脆弱性について公開の issue を作成しないでください。

ライセンス

MIT © Matt Oddie

proxmox-mcpは独立したコミュニティプロジェクトです。Proxmox Server Solutions GmbHとは提携、承認、支援のいずれも受けていません。ProxmoxはProxmox Server Solutions GmbHの登録商標です。