Proxmox MCP is an opinionated MCP server

Proxmox MCP サーバー

NOTE: このプロジェクトは現在活発に開発されています。

動機

最新のインフラでは、Terraform/OpenTofu、Ansible、GitOps などのツールがよく使われています。これらのツールは、Proxmox インフラと Kubernetes クラスターをデプロイおよび構成します。

Proxmox MCP サーバーは、これらのツールに代わるものではありません。AI アシスタントや自動化エージェントが、Proxmox クラスターに関する情報にアクセスできるようにします。

デフォルトのツールは読み取り専用です。バックアップや再起動などの操作を行うツールは、--allow-destructive を指定して有効にできます。

Proxmox の UI で複数のページを確認したり、いくつものコマンドを実行したりする代わりに、AI アシスタントに必要な情報の収集と分析を依頼できます。インフラの変更には、引き続き既存の自動化ツールを主に使用してください。

概要

このサーバーは、AI アシスタントなどの MCP クライアントを Proxmox VE API に接続します。複数の Proxmox クラスターに対応し、構造化データを返します。

次の用途に使用できます。

• クラスター、ノード、ストレージを調査する
• リソース使用率とノードの状態を確認する
• 最近の Proxmox タスクイベントを確認する
• 差異や構成上の問題の可能性を見つける
• インフラを変更する前に情報を収集する

AI の手綱はしっかり握っておきましょう。

Proxmox のコアツール

MCP サーバーは、次の読み取り専用ツールを提供します。

ツール	引数	説明
proxmox_clusters_list	なし	構成済みの Proxmox クラスターを一覧表示します。
proxmox_clusters_describe	cluster	クラスターのバージョン、ノード、ノードの状態、およびリソースの合計を表示します。
proxmox_containers_list	cluster	状態とリソース使用率とともに、LXC コンテナーを一覧表示します。
proxmox_containers_describe	cluster、vmid、node（任意）	LXC コンテナーの現在の状態と、実行中の場合はランタイムネットワークインターフェイスを表示します。
proxmox_events_list	cluster、limit（任意）	すべてのノードで最近発生したタスクイベントを一覧表示します。デフォルトの上限は 10 です。
proxmox_nodes_list	cluster	状態とリソース使用率とともに、ノードを一覧表示します。
proxmox_nodes_describe	cluster、node	ノードの状態、リソース、稼働時間、バージョン、カーネル、起動情報を表示します。
proxmox_storage_list	cluster	状態、種類、コンテンツ、容量使用率とともに、ストレージリソースを一覧表示します。
proxmox_storage_describe	cluster、name、node（任意）	ストレージの詳細を表示します。ノードを指定した場合は、そのノードから見えるコンテンツも表示します。
proxmox_vms_list	cluster	状態とリソース使用率とともに、QEMU 仮想マシンを一覧表示します。
proxmox_vms_describe	cluster、vmid、node（任意）	QEMU ゲストエージェントが応答している場合、QEMU 仮想マシンの現在の状態とゲストネットワークインターフェイスを表示します。

他のツールで使用するクラスター名を確認するには、まず proxmox_clusters_list を使用してください。MCP クライアントから、入力と出力のスキーマ全体を確認できます。コマンドラインからツールを一覧表示することもできます。

proxmox-mcp tools --config /absolute/path/to/cluster-config.yaml

--allow-destructive を有効にすると、proxmox_vms_backup と proxmox_containers_backup は、cluster、vmid、任意の node、 storage、mode、compress の各引数を受け付けます。これらのツールは非同期バックアップを開始し、Proxmox タスク識別子を返します。タスクが作成されても、バックアップがすでに正常に完了したとは限りません。

インストール

Homebrew を使ってローカルにインストールするには、次を実行します。

brew install sergelogvinov/tap/proxmox-mcp

別のマシンでホストされている MCP サーバーを使用する場合、ローカルへのインストールは不要です。

Proxmox クラスターを設定する

1 つ以上の Proxmox クラスターを含む YAML ファイルを作成します。

clusters:
  - region: homelab
    url: https://pve.example.com:8006/api2/json
    token_id: mcp@pve!reader
    token_secret_file: /absolute/path/to/token-secret
    ca_file: /absolute/path/to/proxmox-ca.crt

各クラスターでは、次のフィールドを使用できます。

フィールド	必須	説明
region	はい	ツール呼び出しでクラスターを選択する際に使う一意の名前です。
url	はい	/api2/json を含む Proxmox API の完全な URL です。
token_id	トークン認証の場合	Proxmox API トークン ID です。例：mcp@pve!reader。
token_id_file	トークン認証の場合	トークン ID を含むファイルです。token_id の代わりに使用します。
token_secret	トークン認証の場合	Proxmox API トークンシークレットです。
token_secret_file	トークン認証の場合	トークンシークレットを含むファイルです。token_secret の代わりに使用します。
username	パスワード認証の場合	Proxmox のユーザー名です。password と併用する必要があります。
password	パスワード認証の場合	Proxmox のパスワードです。username と併用する必要があります。
ca_file	いいえ	Proxmox TLS 証明書の検証に使用する CA 証明書のパスです。
insecure	いいえ	TLS 証明書の検証をスキップします。ローカルでのテストにのみ使用してください。デフォルト：false。

クラスターでは、トークン認証またはパスワード認証のどちらか一方を使用してください。シークレットの値を YAML ファイルに含めずに済むため、シークレットにはファイルの使用をおすすめします。 Proxmox アカウントには、ツールに必要な権限のみを付与してください。

--config または CONFIG_FILE で設定ファイルのパスを指定します。

MCP クライアントを設定する

ローカル stdio サーバー

JSON MCP 設定を使用するクライアントでは、次のようなエントリーを追加します。

{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "args": ["mcp"],
      "env": {
        "CONFIG_FILE": "/absolute/path/to/cluster-config.yaml"
      }
    }
  }
}

リモート HTTP サーバー

ストリーム可能な HTTP サーバーを次のように起動します。

proxmox-mcp server \
  --config /absolute/path/to/cluster-config.yaml \
  --listen-address :8080

:8080 は、すべての IPv4 および IPv6 アドレスで接続を受け付けます。特定のアドレスで待ち受けるには、127.0.0.1:8080 や [::1]:8080 のようにポートとともに指定します。 MCP エンドポイントは http://host:8080/mcp です。

リモートクライアントでは、末尾が /mcp の HTTPS URL を使用します。

{
  "mcpServers": {
    "proxmox": {
      "type": "http",
      "url": "https://proxmox-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer PVEAPIToken=mcp@pve!reader=TOKEN_SECRET"
      }
    }
  }
}

サーバーは HTTP エンドポイントのユーザー認証を提供しません。 アクセス制御には、Proxmox 認証と API トークンを使用します。 次のように、mcp ヘッダーでトークンを指定します。

Authorization: PVEAPIToken=mcp@pve!reader=TOKEN_SECRET

このヘッダーが指定されている場合、クラスター設定の認証情報の代わりに、そのトークンがツール呼び出しに使用されます。設定するクラスターには、引き続き region と url が必要です。

設定を保存した後、MCP クライアントを再起動または再読み込みしてください。

実行

共通フラグ

mcp、server、tools コマンドでは、次のフラグを使用します。各フラグは環境変数でも設定できます。コマンドラインフラグは環境変数より優先されます。

フラグ	環境変数	デフォルト	説明
--config <path>	CONFIG_FILE	なし	必須のクラスター YAML 設定ファイルのパスです。
--extensions <list>	EXTENSIONS	all	有効にする拡張機能をカンマ区切りで指定するリスト、または all です。
--allow-destructive	ALLOW_DESTRUCTIVE	false	使用可能な場合に、破壊的なツールを許可します。現在のコアツールは読み取り専用です。
--log-level <level>	LOG_LEVEL	info	ログレベル：debug、info、warn、error のいずれかです。
--log-format <format>	LOG_FORMAT	text	ログ出力形式：text または json です。

server コマンドでは、--listen-address または LISTEN_ADDRESS（host:port）も指定できます。デフォルトは 127.0.0.1:8080 で、コンテナーイメージでは LISTEN_ADDRESS=:8080 が設定されます。tools コマンドでは、text、json、yaml を指定する --output（-o）を使用できます。デフォルトは text です。

たとえば、stdio サーバーを JSON ログで実行するには、次のようにします。

proxmox-mcp mcp \
  --config /absolute/path/to/cluster-config.yaml \
  --log-format json

設定をテストする

使用可能なツールをすべて一覧表示します。

export CONFIG_FILE="/absolute/path/to/cluster-config.yaml"
proxmox-mcp tools

ツールを直接呼び出します。

proxmox-mcp tools proxmox_clusters_list
proxmox-mcp tools proxmox_nodes_list cluster=homelab
proxmox-mcp tools -o json proxmox_events_list cluster=homelab limit=5

ライセンス

Apache License, Version 2.0（「ライセンス」）に基づいてライセンスされています。 このファイルは、ライセンスに従う場合にのみ使用できます。 ライセンスのコピーは、以下から入手できます。

http://www.apache.org/licenses/LICENSE-2.0

ライセンスで要求される場合、または書面で合意された場合を除き、 ライセンスに基づいて配布されるソフトウェアは、「現状有姿」で配布され、 明示または黙示を問わず、いかなる保証や条件も付されません。 ライセンスに基づく権利と制限を規定する具体的な文言については、 ライセンスをご確認ください。

---

Proxmox® は、Proxmox Server Solutions GmbH の登録商標です。