Proxmox Mcp

Proxmox MCP サーバー

シンプルな Proxmox MCP

Proxmox VE を管理する MCP サーバー

50 個のツール — ノード、QEMU VM、LXC コンテナー、ストレージ、クラスター、スナップショット。

このサーバーを選ぶ理由

• イメージは 1 つ、マルチアーキテクチャ対応 — docker run ghcr.io/akmalovaa/proxmox-mcp:latest を実行するだけです
• 環境変数だけ — 設定ファイルもデータベースも状態も不要です
• デフォルトで読み取り専用 — 破壊的な操作は、明示的に PROXMOX_RISK_LEVEL を指定しない限り実行できません
• stdio または Streamable HTTP — 環境変数を 1 つ変えるだけです。デフォルトは stdio で、HTTP はループバックにバインドします
• 小さなコードベース — Proxmoxer の上に薄いレイヤーを設けており、設定ファイルもデータベースも状態もありません
• 未加工の JSON を出力 — 書式設定も絵文字もなく、LLM が扱いやすいクリーンなデータを取得できます
• 読みやすいエラー — 403、ホストの停止、またはリスクレベルによるブロックは、スタックトレースではなく文章で返されます

クイックスタート

イメージ： ghcr.io/akmalovaa/proxmox-mcp:latest（マルチアーキテクチャ対応：amd64 + arm64）。

1. シェルのプロファイルに認証情報をエクスポートします（~/.zprofile、~/.zshrc または ~/.bashrc）：

# token auth (recommended — see "Least privilege" for the user and role to give it):
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=mcp@pve
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# or password auth:
# export PROXMOX_USER=root@pam
# export PROXMOX_PASSWORD=your-password

# optional:
export PROXMOX_RISK_LEVEL=read

再読み込みするには、source ~/.zprofile を実行します（またはシェルを再起動します）。

2. ~/.claude/settings.json（Claude Code）または claude_desktop_config.json（Claude Desktop）に追加します：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

または、トークン認証を使用します：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

値を指定せずに docker run -e VAR を実行すると、ホストの環境変数が引き継がれるため、設定ファイルにシークレットを記載する必要はありません。クライアントを再起動すると、読み取り専用の Proxmox ツールが 32 個利用可能になります（PROXMOX_RISK_LEVEL を引き上げると、さらに増えます）。

パスワード認証の場合は、トークン用の変数を PROXMOX_PASSWORD に置き換えてください。

注： macOS の Claude Desktop は launchd 経由で起動されるため、~/.zprofile／~/.zshrc の設定は引き継がれません。エクスポート設定を ~/.zshenv に記述するか、設定ファイル内にインラインの "env": { ... } ブロックを記述してください。

設定

すべての設定は環境変数です。シェルのプロファイルに設定するか、docker run -e にインラインで渡すか、MCP クライアントの env ブロックに宣言してください。

変数	デフォルト	説明
PROXMOX_HOST	—	Proxmox ホスト（IP アドレスまたはホスト名）
PROXMOX_USER	root@pam	API ユーザー
認証	—	トークン または パスワード — 詳細は以下を参照
PROXMOX_PORT	8006	API ポート
PROXMOX_VERIFY_SSL	false	TLS 証明書を検証するかどうか
PROXMOX_TIMEOUT	15	各 API リクエストの待機時間（秒）
PROXMOX_RISK_LEVEL	read	read / lifecycle / all — リスクレベルを参照
PROXMOX_TOOLS_ALLOW	—	リスクレベルに加えて登録するツール名をカンマ区切りで指定
PROXMOX_REDACT_SECRETS	true	レスポンス内の cipassword / sshkeys をマスクするかどうか

トランスポート設定は PROXMOX_MCP_ プレフィックスの下にあります。Streamable HTTPを参照してください。

認証：トークン または パスワード

どちらか一方を選んでください。両方が設定されている場合は、トークンが優先されます。

トークン（推奨）：

export PROXMOX_USER=mcp@pve
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

ペアの片方だけを設定すると、パスワードへ暗黙にフォールバックせず、起動エラーになります。以前は、PROXMOX_TOKEN_NAME の入力ミスにより、PROXMOX_USER として気付かないまま実行されていました。

パスワード（代替）：

export PROXMOX_PASSWORD=your-password

最小権限

MCP サーバーは、モデルが自分で書いていないテキストに基づいて動作するため、root@pam ではなく、専用のユーザーと専用のトークンを用意してください。Proxmox ホストで次を実行します。

# a user that is not root, with a role that matches the risk level you plan to run
pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor          # read
# pveum acl modify / --users mcp@pve --roles PVEVMAdmin        # lifecycle / all

# a token for that user. Privilege Separation ON (the default) means the token starts
# with no rights at all, so grant it the same role explicitly:
pveum user token add mcp@pve mcp --privsep 1
pveum acl modify / --tokens 'mcp@pve!mcp' --roles PVEAuditor

トークンに実際に設定された権限を確認します。

pveum user permissions mcp@pve --token mcp

PVEAuditor は、読み取り専用の 32 個のツールすべてをカバーします。/vms に対する PVEVMAdmin は、ゲストのライフサイクル管理とスナップショットを追加します。さらに、migrate_vm にはターゲットノードでの VM.Migrate が、clone_vm にはターゲットストレージでの Datastore.AllocateSpace が必要です。サーバーにクラスターの一部だけを見せる場合は、ACL のパスを絞り込んでください（/vms/101、/pool/homelab）。

root@pam も引き続き使用でき、ローカルでさっと確認するには最も手軽です。ただし、そのまま実行し続けるべきではありません。

リスクレベル

PROXMOX_RISK_LEVEL は、使用可能なツールを制御します。現在のレベルを超えるツールは登録されないため、MCP クライアントのツール一覧には表示されません。

レベル	ツール数	追加されるもの
read (デフォルト)	32	読み取り専用ツール
lifecycle	46	+ start / stop / reboot / suspend / clone / migrate / create-snapshot
all	50	+ delete-snapshot / rollback-snapshot

各レベル引き上げ対象の呼び出しは、呼び出し時にも再チェックされ、標準エラー出力に記録されます（ALLOW / DENY + ツール + ティア）。

クライアント側からは、ほかに現在のレベルを確認できません。存在しないツールは、最初から作られていなかったツールと同じように見えます。そのため、get_server_info はバージョンとツール数に加えて、現在のレベルも報告します。

特定のエージェントにサービスを提供するデプロイでは、PROXMOX_TOOLS_ALLOW を使って、ティア内のツールをさらに絞り込めます。

export PROXMOX_TOOLS_ALLOW=list_nodes,list_containers,get_container_status,get_cluster_resources

存在しない名前を指定すると起動エラーになるため、入力ミスによってツール一覧が気付かないうちに削られることはありません。特別な理由がない限り、get_server_info は一覧に残してください。クライアントが、ほかのツール一覧の意味を知るために使うツールです。

応答の形式

インベントリ一覧（list_nodes、list_vms、list_containers、get_cluster_resources）は、各行のうち、識別情報、ステータス、稼働時間、CPU、メモリのコンパクトな一部を返します。除外されるのは、1 秒あたりの I/O カウンターと PSI 圧力ゲージです。実データではありますが、トリアージの判断には影響せず、保持されるデータの数倍の量になります。未加工の行を取得するには、verbose=true を渡してください。

書き込みツールが返すのは、タスクの完了結果ではなく、Proxmox が受け付けたタスクです。

{"state":"accepted","operation":"start_vm","node":"pve","vmid":101,
 "upid":"UPID:pve:...","poll_with":"get_task_status"}

cipassword と sshkeys は、キーを残したまま、すべての場所で ***redacted*** に置き換えられます。これにより、モデルは cloud-init が設定されていることを引き続き判別できます。未加工の値を取得するには、PROXMOX_REDACT_SECRETS=false を設定してください。

ストリーミング可能な HTTP

stdio は引き続きデフォルトであり、ローカルマシン上の MCP クライアントではこれを使用してください。共有デプロイメント（クラスター内のコンテナや、1 つの URL を複数のクライアントで共有する場合）では、トランスポートを設定するだけで、ほかは何も変わりません。

docker run --rm -p 8000:8000 \
  -e PROXMOX_HOST -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  -e PROXMOX_MCP_TRANSPORT=streamable-http \
  -e PROXMOX_MCP_HOST=0.0.0.0 \
  -e PROXMOX_MCP_ALLOWED_HOSTS=proxmox-mcp.example.com \
  ghcr.io/akmalovaa/proxmox-mcp:latest

変数	デフォルト	説明
PROXMOX_MCP_TRANSPORT	stdio	stdio または streamable-http
PROXMOX_MCP_HOST	127.0.0.1	バインドアドレス。コンテナでは 0.0.0.0
PROXMOX_MCP_PORT	8000	ポート
PROXMOX_MCP_PATH	/mcp	エンドポイントのパス
PROXMOX_MCP_JSON_RESPONSE	true	SSE ストリームの代わりに JSON レスポンスを返します
PROXMOX_MCP_ALLOWED_HOSTS	—	許可する Host ヘッダー。* を指定するとチェックを無効にします
PROXMOX_MCP_ALLOWED_ORIGINS	—	許可するブラウザーのオリジン。空の場合は同一オリジンのみ

プレフィックスが PROXMOX_ ではなく PROXMOX_MCP_ なのは、Kubernetes がリンクされた各 Service に対して <SERVICE>_PORT を設定するためです。proxmox という名前の Service があると、PROXMOX_PORT が上書きされてしまいます。

セッションは使用しません（stateless_http）。セッションはリビジョン 2026-07-28 でプロトコルから削除されており、セッションがなければ複数のクライアントで 1 つの URL を共有でき、ローリングアップデートによって接続が切断されることもありません。

Host と Origin の検証。 ループバック以外にバインドするには、PROXMOX_MCP_ALLOWED_HOSTS が必要です。設定されていない場合、サーバーは起動を拒否します。外部の Origin には 403 を、想定外の Host には 421 を返します。これにより、同じ LAN 内のブラウザーのページが DNS リバインディングを介してサーバーを操作するのを防ぎます。Origin ヘッダーのないリクエスト（curl、MCP クライアント）は常に許可されます。前段の何かですでに検証している場合に限り、PROXMOX_MCP_ALLOWED_HOSTS=* を設定してください。

認証機能はありません。 エンドポイントにアクセスできる人は誰でも、PROXMOX_RISK_LEVEL で許可されている操作を実行できます。信頼できるゲートウェイ、認証プロキシ、またはネットワーク境界の背後に配置し、アクセス経路が認証されていない場合は PROXMOX_RISK_LEVEL=read のままにしてください。

ヘルスエンドポイントは /mcp と並行して提供され、認証は不要です。

パス	意味
GET /healthz	プロセスが稼働しています。Proxmox には一切アクセスしません。Proxmox の停止時に失敗する Liveness Probe を設定すると、サーバーがループ状態で再起動するだけで、何も解決しません。
GET /readyz	Proxmox が version.get() に応答しました。トラフィックの振り分け条件にはこちらを使用してください。応答できない場合は、理由を読み取れる 503 を返します。

livenessProbe:
  httpGet: { path: /healthz, port: 8000 }
readinessProbe:
  httpGet: { path: /readyz, port: 8000 }

対話形式での使用時は、フラグで環境変数と同じ設定ができます。例：uvx proxmox-ve-mcp --transport streamable-http --port 8080

Sentry（任意）

ツールの呼び出しや失敗を Sentry に送信できます。すべての tools/call がスパンになり、失敗したツールはそれぞれ Issue になります。SENTRY_DSN が未設定の場合、データは一切送信されず、SDK もインポートされません。

ghcr.io イメージには SDK が含まれています。PyPI からインストールする場合は、追加パッケージをインストールしてください。

uvx --from 'proxmox-ve-mcp[sentry]' proxmox-ve-mcp

変数	デフォルト	説明
SENTRY_DSN	—	レポートを有効にするには設定します
SENTRY_ENVIRONMENT	production	任意の環境ラベル
SENTRY_TRACES_SAMPLE_RATE	1.0	トレースするツール呼び出しの割合
SENTRY_SEND_DEFAULT_PII	false	ツールの引数と結果をスパンデータとして送信します

意図がない限り、SENTRY_SEND_DEFAULT_PII は無効のままにしてください。有効にすると、ツールの引数と結果がスパンに添付され、get_vm_config は SSH キーと cipassword のハッシュを返します。追加パッケージをインストールせずに DSN を設定すると、警告がログに記録されますが、サーバーはそのまま動作します。

ツール

ノード（10）

ツール	説明
list_nodes	ステータス、CPU、メモリ、稼働時間を含む、すべてのクラスターノードを一覧表示します
get_node_status	ノードの詳細なメトリクス（CPU、メモリ、ディスク、負荷、カーネル）
get_node_networks	ノード上のネットワークインターフェース
get_node_disks	ノード上の物理ディスク
get_node_services	Proxmox のシステムサービスとその状態
get_node_updates	保留中の APT パッケージ更新
get_node_rrd_data	CPU／メモリ／ディスク／ネットワークの過去のメトリクス（RRD）
get_node_tasks	ノード上の最近のタスク。エラーのみへの絞り込みも可能
get_task_status	UPID で指定したタスクのステータス
get_task_log	タスクのログ出力

QEMU VM（17）

ツール	ティア	説明
list_vms	read	すべての VM を一覧表示します。ノードによる絞り込みも可能です
get_vm_status	read	VM の現在のステータス（稼働中／停止中、CPU、メモリ）
get_vm_config	read	VM の設定（ハードウェア、ディスク、ネットワーク）
get_vm_network_interfaces	read	稼働中の VM のIP アドレス（QEMU ゲストエージェント経由）
get_vm_rrd_data	read	CPU／メモリ／ディスク／ネットワークの過去のメトリクス（RRD）
list_vm_snapshots	read	VM のすべてのスナップショットを一覧表示します
start_vm	lifecycle	VM を起動します
stop_vm	lifecycle	VM を強制停止します — 破壊的操作として注記されています。保存されていないゲストの状態は失われます
shutdown_vm	lifecycle	タイムアウト付きの ACPI による正常なシャットダウン
reboot_vm	lifecycle	ACPI 経由で再起動します
suspend_vm	lifecycle	VM を一時停止します
resume_vm	lifecycle	一時停止中の VM を再開します
clone_vm	lifecycle	フルクローンまたはリンククローンを作成します
migrate_vm	lifecycle	VM をオンラインまたはオフラインで別のノードに移動します
create_vm_snapshot	lifecycle	スナップショットを作成します
delete_vm_snapshot	all	スナップショットを削除します
rollback_vm_snapshot	all	スナップショットにロールバックします

LXC コンテナー（13）

ツール	ティア	説明
list_containers	read	すべての LXC コンテナーを一覧表示します。ノードによる絞り込みも可能です
get_container_status	read	コンテナーの現在のステータス
get_container_config	read	コンテナーの設定
get_container_interfaces	read	稼働中のコンテナーのIP アドレス
get_container_rrd_data	read	CPU／メモリ／ディスク／ネットワークの過去のメトリクス（RRD）
list_container_snapshots	read	すべてのスナップショットを一覧表示します
start_container	lifecycle	コンテナーを起動します
stop_container	lifecycle	コンテナーを強制停止します — 破壊的操作として注記されています
shutdown_container	lifecycle	タイムアウト付きの正常なシャットダウン
reboot_container	lifecycle	コンテナーを再起動します
create_container_snapshot	lifecycle	スナップショットを作成します
delete_container_snapshot	all	スナップショットを削除します
rollback_container_snapshot	all	スナップショットにロールバックします

ストレージ（2）

ツール	説明
list_storage	使用状況を含むストレージプール。ノードによる絞り込みも可能です
get_storage_content	ストレージプールの内容（ISO、バックアップ、イメージ、テンプレート）

クラスター（7）

ツール	説明
get_cluster_status	クラスターの健全性、クォーラム、ノードメンバーシップ
get_cluster_resources	すべてのリソース（VM、コンテナー、ストレージ、ノード）
get_cluster_backups	設定済みのバックアップジョブ
get_ha_status	高可用性リソースとその状態
list_pools	リソースプール
get_cluster_log	クラスター全体のイベントログ。新しい順
get_next_vmid	次に利用可能な VM／コンテナー ID

サーバー（1）

ツール	説明
get_server_info	このサーバー自身のリスクレベル、ツール数、バージョン、Proxmox への接続可否

アーキテクチャ

src/proxmox_mcp/
├── server.py    # MCPServer instance, health routes, transport selection, entry point
├── config.py    # Pydantic Settings (PROXMOX_) + transport config (PROXMOX_MCP_)
├── client.py    # Proxmoxer connection, built once per process
└── tools/       # nodes, vms, containers, storage, cluster, server_info

• デフォルトで読み取り専用 — 高リスクのツールは PROXMOX_RISK_LEVEL で制御します
• 登録時に制御 — ティアを超えるツールは呼び出し時に拒否されるのではなく、tools/list に表示されません。モデルに見えないものは、再試行できません
• 利用許可とアノテーションは別々 — tier= はオペレーターのポリシーで、annotations= はクライアントに呼び出しの内容を伝えるものです。そのため、強制停止は destructiveHint: true でありながら、lifecycle ティアに属することができます
• 遅延接続 — Proxmoxer クライアントは初回使用時に一度だけ構築され、共有されます。そのため、Proxmox に到達できない場合でもサーバーは正常に起動します
• 生の JSON 出力 — コンパクトで書式なしのため、LLM がデータを直接処理します
• エラーの正規化 — Proxmox とネットワークの障害は、requests のトレースバックではなく、対処方法がわかる一文に変換されます

開発

単独で実行する（テスト用）

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

Docker を使わない場合（UV）

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

MCP クライアントの設定：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "python", "-m", "proxmox_mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

ソースからビルドする

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

イメージはマルチステージです。uv が使い捨てレイヤーで仮想環境をビルドし、ランタイムステージには Python と仮想環境のみを含め、非特権ユーザー mcp（uid 10001）として実行します。

リント、型チェック、テスト

uv sync --locked --group dev
uv run ruff check .
uv run mypy src/
uv run pytest -v

ライセンス

MIT