ProxmoxMCP-Plus

ProxmoxMCP-Plus

MCP クライアント、AI エージェント、OpenAPI ツールを通じて Proxmox VE を操作できます。VM、LXC、スナップショット、バックアップ、ISO、コンテナーコマンド、永続的な長時間実行ジョブを対象とする、セキュリティを重視した単一の制御プレーンです。

クイックスタート | クライアントのインストール | デモ | ツール | 安全性 | シナリオ | ドキュメント | Wiki

MCP と OpenAPI は同じワークフローへの代替エントリーポイントであり、別々のプロセスで実行できます。実線の矢印はリクエストと実行を、破線の矢印は永続化されたジョブと監査の状態を示します。承認ゲート、SSH 実行、MCP HTTP OAuth は設定に依存します。図を選択すると、全体表示で確認できます。

ProxmoxMCP-Plus を選ぶ理由

ProxmoxMCP-Plus は AI クライアントと Proxmox VE の間に位置し、オペレーターがワークフローごとに生の API 呼び出し、場当たり的なシェルスクリプト、独自のジョブポーリングを組み合わせる必要がないようにします。

同じ運用機能を、次の 2 つの方法で提供します。

• MCP：Claude Desktop、Cursor、VS Code、Open WebUI、Codex、その他の MCP 対応エージェント向け
• OpenAPI：HTTP 自動化、ダッシュボード、社内ツール、ノーコードワークフロー向け

提供する機能：

• VM と LXC のライフサイクル操作
• スナップショットの作成、ロールバック、削除
• バックアップと復元のワークフロー
• ISO のダウンロードとクリーンアップ
• ノード、ストレージ、クラスターの調査
• ガードレール付きの SSH ベースのコンテナーコマンド実行
• オプトイン方式で保護されたProxmox ノードの SSH コマンド
• 非同期の Proxmox タスクを追跡する永続ジョブ管理

他との違い

優先事項	プロジェクトでの対応
2 つのアクセス経路	エージェントのワークフロー向けのネイティブ MCP と、標準的な HTTP 自動化向けの OpenAPI
Proxmox 向けワークフロー	VM、LXC、スナップショット、バックアップ、ISO、ストレージ、クラスターの日常的な運用
長時間実行される操作	安定した job_id、Proxmox の UPID 追跡、ポーリング、再試行、キャンセル、監査履歴
より安全な実行	Proxmox API トークン、OpenAPI ベアラー認証、コマンドポリシー、承認トークン、TLS 検証、MCP HTTP の Host／Origin 制御
実際の検証	単体テスト、統合テスト、Docker／OpenAPI、Proxmox のライブ e2e テストのエントリーポイントをリポジトリ内で説明

クイックスタート

1. Proxmox 認証情報を準備する

ワークフローで必要な権限だけを付与した Proxmox API トークンを作成します。次に、ローカルの設定ファイルを作成します。

cp proxmox-config/config.example.json proxmox-config/config.json

続いて、環境に合わせて proxmox-config/config.json を編集します。最低限、次の項目が必要です。

• proxmox.host
• proxmox.port
• auth.user
• auth.token_name
• auth.token_value

コンテナー内でコマンドを実行する場合は、ssh セクションも追加します。 ジョブの状態をデフォルトのローカル SQLite ファイル以外に保存する場合は、jobs セクションを追加します。

実際のライブ検証には、proxmox-config/config.live.example.json を元に作成した専用の proxmox-config/config.live.json を使用します。 ローカル API トンネルを意図的に実行する場合を除き、ライブ E2E でプレースホルダーやローカル専用の config.json を参照しないでください。

ジョブの永続化に関する任意の設定：

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

任意のツール公開フィルタリングを使用すると、MCP クライアントに送信されるスキーマを減らせます。 デフォルトでは無効になっているため、既存の設定では引き続きすべての利用可能なツールが公開されます。mcp の下で、次のいずれか一方のモードを設定します。

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

または、tool_denylist、あるいはカンマ区切りの環境変数 MCP_TOOL_ALLOWLIST と MCP_TOOL_DENYLIST を使用します。両方のモードを設定しないでください。環境変数による選択は、ファイルレベルのフィルタリングモードに優先します。空の許可リストではツールが一切公開されず、空の拒否リストではすべてのツールが公開されます。ツール名は小文字で正確に指定する必要があります。未知の名前があると起動に失敗するため、タイプミスによってアクセス範囲が意図せず広がることはありません。フィルターを変更したら、MCP サーバーを再起動するか、再接続してください。

2. ランタイムの実行方法を1つ選ぶ

方法	最適な用途	起動コマンド	確認方法
PyPI からの MCP stdio	Claude Desktop、Cursor、VS Code、Codex、ローカルエージェント	uvx proxmox-mcp-plus	クライアントに get_nodes、get_vms、ジョブ関連ツールが表示される
Docker からのネイティブ MCP HTTP	Streamable HTTP に対応したリモート MCP クライアント	docker compose --profile mcp-http up -d proxmox-mcp-http	http://localhost:8000/mcp に接続する
Docker からの OpenAPI ブリッジ	HTTP クライアント、ダッシュボード、スクリプト、ノーコードツール	docker compose --profile openapi up -d proxmox-mcp-api	curl -f http://localhost:8811/livez

Docker の例では、デフォルトでホストポートを 127.0.0.1 に公開します。Compose モードは明示的に有効化する必要があります。選択したモードのキーのみを設定してください。ネイティブ HTTP では MCP_API_KEY、OpenAPI では PROXMOX_API_KEY を使用します。リバースプロキシ、トンネル、明示的な LAN バインド、コンテナーの再作成については、Compose のデプロイとアップグレードに関する注意事項を参照してください。

PyPI を使用した MCP stdio

uvx proxmox-mcp-plus

または、先にインストールします。

pip install proxmox-mcp-plus
proxmox-mcp-plus

MCP クライアントがローカルの stdio サーバーを起動する場合は、この方法を使用してください。

Code Mode（オプトイン）

Code Mode は、従来の完全なツールカタログを維持するため、デフォルトでは無効になっています。有効にするには、設定ファイルで mcp.code_mode: true を指定するか、MCP_CODE_MODE=true を設定します。有効にすると、MCP が公開するツールは proxmox_code_search、proxmox_code_get_schema、proxmox_code_execute の3つになります。コード実行は隔離されたサンドボックス内で行われ、既存の検証、ポリシー、承認の経路を通じてドメインツールにアクセスします。検出にはフィルタリング済みの実行時カタログを使用するため、インストール済みの wheel でも機能します。例：

await call_tool("get_nodes", {"target": "default"})

最後の式は data.result として返されます。ツールの結果には MCP JSON コンテンツブロック（提供されている場合は構造化コンテンツも）が使用されます。target や承認トークンなどの引数については、proxmox_code_get_schema を使用してください。スクリプトは、登録済みツールの呼び出しを除き、ファイルシステムやネットワークにアクセスできません。制限：ソースコードは64,000文字、サンドボックスのメモリは100 MB、ツール呼び出しは25回、最終 JSON は16 KB、同時実行は2件までです。実行時間の上限は30秒です。スクリプトをキャンセルまたは失敗しても、ツールの副作用はロールバックされません。失敗した変更スクリプトを自動的に再試行しないでください。

オプションのワーカー再利用：mcp.code_mode_pool_reuse: true または MCP_CODE_MODE_POOL_REUSE=true を設定します。デフォルトでは、実行ごとに新しいワーカーを起動します。再利用を有効にすると、サーバーの稼働中に最大2つのワーカーを保持し、それぞれ100回チェックアウトされた後に再起動します。リクエストごとに新しいサンドボックスセッションを開始します。グローバル変数、承認、出力コレクター、呼び出し回数の制限は、リクエスト間で共有されません。HTTP クライアントはサーバー所有のプールを共有します。クライアントが切断されても、プールは閉じられません。python scripts/benchmark_code_mode.py を実行すると、ローカルでの起動オーバーヘッドを測定できます。これはマイクロベンチマークであり、Proxmox 操作のレイテンシを推定するものではありません。

Docker でのネイティブ MCP HTTP

リモート MCP クライアントが Streamable HTTP に対応している場合は、この方法を使用します。

export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

MCP クライアントの接続先：

http://127.0.0.1:8000/mcp

リモートクライアントでは、設定済みのプロキシ／トンネル URL を使用するか、Docker デプロイの説明に従ってホストのバインド範囲を明示的に広げてください。

ネイティブ MCP HTTP リクエストごとに、Authorization: Bearer <MCP_API_KEY> を送信してください。このキーは Proxmox の認証情報とは別のものです。ネイティブの Streamable HTTP と SSE では、デフォルトでキーが必要です。Tailscale ACL などの外部アクセス制御レイヤーで保護されたエンドポイントでは、JSON 設定で MCP_ALLOW_UNAUTHENTICATED_HTTP=true または mcp.allow_unauthenticated_http: true を明示的に設定してください。これによりキーなしで起動でき、警告がログに記録されますが、外部アクセス制御の設定や検証は行われません。MCP_API_KEY が設定されている場合は、オプトアウトしていても常に適用されます。この設定は OpenAPI 認証にも DNS リバインディング保護にも影響しません。

MCP クライアント向け OAuth ブラウザーゲート

ネイティブ MCP HTTP では、オペレーターが管理する人間向けの認証情報を MCP_API_KEY のみに保ちながら、PKCE を使用した OAuth 認可コードフローをオプションで公開できます。OAuth プロトコルの処理は MCP Python SDK（mcp>=1.30.0,<2）に委任され、API キーの同意ポリシーと永続的な OAuth 状態は ProxmoxMCP-Plus が提供します。

OAuth の状態は PostgreSQL に保存されます。これにより、複数の MCP サーバーインスタンスまたはホストを明示的にデプロイした場合、ローカルファイルシステムに依存せず、登録済みクライアント、認可コード、アクセストークン、リフレッシュトークン、リフレッシュトークンのリプレイ保護、ログイン試行回数制限の状態を共有できます。

クライアントは SDK の /authorize エンドポイントから開始します。SDK がクライアント、リダイレクト URI、スコープ、PKCE リクエスト、リソースを検証すると、ブラウザーは同じ MCP オリジン上の /oauth/consent にリダイレクトされます。ユーザーはクライアント名、リダイレクト先のオリジン、要求されたスコープを確認してから、MCP_API_KEY を入力します。API キーが URL に含まれることも、OAuth クライアントに返されることもありません。

必須の OAuth 設定：

export MCP_API_KEY="$(openssl rand -hex 32)"
# Replace <password> with the database user's password.
export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:<password>@postgres.example:5432/proxmox_oauth'

サーバーの設定例：

docker run --rm -p 127.0.0.1:8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -e MCP_OAUTH_ENABLED=true \
  -e MCP_OAUTH_ISSUER=https://mcp.example.com \
  -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \
  -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

次に、OAuth 対応クライアントを以下に接続します：

https://mcp.example.com/mcp

OAuth モードでは、同じ公開オリジン上に以下のエンドポイントが公開されます：

• /.well-known/oauth-protected-resource/mcp - RFC 9728 保護対象リソースのメタデータ
• /.well-known/oauth-authorization-server - SDK 認可サーバーメタデータ
• /register - SDK 動的クライアント登録（DCR）
• /authorize - SDK 認可エンドポイント
• /token - SDK 認可コード／リフレッシュトークン交換
• /oauth/consent - ProxmoxMCP-Plus API キーの同意ページ

SDK では PKCE S256 が必須であり、発行された OAuth アクセストークンで MCP リソースを保護します。ブラウザーの同意トランザクションは有効期間が短く、HMAC 署名付きでステートレスです。永続的な OAuth 状態はすべて PostgreSQL に保存されます。

認可コードの消費とリフレッシュトークンのローテーションには、PostgreSQL のトランザクションを使用します。コードまたはリフレッシュトークンの削除と、置き換えトークンの挿入をアトミックに行うため、同じ認証情報を複数のサーバーインスタンスで同時に再利用することはできません。動的クライアント登録数の制限も、PostgreSQL のトランザクションスコープのアドバイザリロックで直列化されます。設定された上限を超える前に、非アクティブな登録が削除されます。

MCP_API_KEY は、ブラウザーの同意で使う認証情報の唯一の信頼できる情報源です。このランタイムでは、キーやその検証子を PostgreSQL に保存しません。サーバープロセスは、環境変数で指定された値と直接照合して同意を検証します。サービスを複数のコンテナーまたはインスタンスとして明示的にデプロイする場合は、各インスタンスに同じシークレットを設定してください。キーを変更する前にすべてのインスタンスを停止し、新しい値で全インスタンスを再起動または再作成してから、再度トラフィックをルーティングしてください。既存の OAuth クライアントと発行済みトークンはブラウザーゲートのキーとは独立しており、有効期限が切れるか取り消されるまで有効です。

OAuth が有効な場合に必須：

変数	用途
MCP_API_KEY	同意ページでのみ入力する人間用の認証情報
MCP_OAUTH_ISSUER	この MCP 認可サーバーの公開 HTTPS オリジン
MCP_OAUTH_DATABASE_URL	OAuth 状態の保存に使用する PostgreSQL DSN

OAuth 環境変数（任意）：

変数	デフォルト	用途
MCP_OAUTH_RESOURCE	<issuer>/mcp	公開 MCP リソース識別子。発行者と同じオリジンを使用する必要があります
MCP_OAUTH_SCOPES	mcp	必須スコープのコンマ区切りリスト
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS	3600	アクセストークンの有効期間
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS	2592000	リフレッシュトークンの有効期間（30 日）
MCP_OAUTH_MAX_REGISTERED_CLIENTS	4096	非アクティブなクライアントを削除する前に永続化できる DCR クライアントの最大数
MCP_OAUTH_DB_POOL_MIN_SIZE	1	MCP プロセスあたりの asyncpg 接続の最小数
MCP_OAUTH_DB_POOL_MAX_SIZE	10	MCP プロセスあたりの asyncpg 接続の最大数
MCP_OAUTH_DB_COMMAND_TIMEOUT_SECONDS	10	OAuth ストアが使用する PostgreSQL コマンドのタイムアウト
MCP_OAUTH_CLIENT_IP_HEADER	未設定	ログインのレート制限にのみ使用する、信頼済みリバースプロキシのヘッダー

ブラウザーゲートの認証情報をローテーションするには、この発行者を使用しているすべての MCP インスタンスを停止し、デプロイ環境の MCP_API_KEY を更新したうえで、すべてのインスタンスを同じ新しいキーで再起動または再作成してください。環境変数はプロバイダーの起動時に読み込まれます。実行中のコンテナーの環境変数を編集しても、キーは再読み込みされません。OAuth データベースのメタデータやキーのバージョンを更新する必要はありません。以前のキーで作成された保留中の同意トランザクションは、すべてのインスタンスの再起動後に検証できなくなります。発行済みの OAuth トークンは、通常の有効期間と取り消しルールに従います。キーのローリング変更中は、旧インスタンスが旧キーを受け付け続け、異なるキーを持つインスタンス間でルーティングされた同意リクエストは失敗します。古いインスタンスを検出または無効化するデータベースの仕組みはありません。ブラウザーゲートのキーを変更しても、既存のアクセストークン、リフレッシュトークン、認可コードは取り消されません。侵害された OAuth 認証情報は、明示的に取り消してください。 MCP_OAUTH_KEY_VERSIONを使用していたOAuthビルドからアップグレードする場合、起動時に旧変数は無視され、proxmox_mcp_oauth_metadataは変更されません。新規データベースではこのテーブルは作成されません。登録済みクライアントと発行済みのOAuth認証情報は保持され、手動でのSQL移行は不要です。レガシーメタデータを保持することで、旧ワーカーのクエリが壊れるのを防ぎ、同じAPIキーとレガシーキーのバージョンを使用してロールバックできます。アップグレード前にデータベースをバックアップし、キーをローテーションする前にすべての旧インスタンスを停止してください。キーを変更すると、レガシーメタデータには引き続き旧キーの情報が記録されます。ロールバックするには、旧設定を復元するか、旧バージョンのローテーション手順に従う必要があります。この手順ではOAuthの状態が無効になります。すべての旧インスタンスを廃止し、ロールバックが不要になった場合に限り、レガシーテーブルを手動で削除してください。このテーブルには、以前のキーの検証子が残っている可能性があります。

データベースロールには、そのデータベース内のproxmox_mcp_oauth_*テーブルを作成および変更する権限が必要です。これらのテーブルには、発行済みクライアントシークレットを含むOAuthクライアントのメタデータのほか、認可コードと有効なトークンが含まれます。そのため、PostgreSQLデータベースとバックアップは認証情報の保管場所として保護する必要があります。

複数のMCPインスタンスが同じMCP_OAUTH_DATABASE_URLを使用する場合、OAuthの状態とワンタイムトークンの適用はインスタンス間で共有されます。設定されたプールの上限はプロセスごとに適用されるため、MCPプロセスの総数を考慮してデータベースの容量を確保してください。

サーバーが信頼できるリバースプロキシの背後にあり、ユーザーごとのログインレート制限で元のクライアントアドレスを使用する必要がある場合は、プロキシが上書きするヘッダー（たとえばCF-Connecting-IP）をMCP_OAUTH_CLIENT_IP_HEADERに設定してください。クライアントによるそのヘッダーの偽装をプロキシが防止していない場合を除き、設定しないでください。

MCP_OAUTH_ENABLED=trueの場合、/mcpへのAuthorization: Bearer <MCP_API_KEY>による直接リクエストは意図的に拒否されます。APIキーが受け付けられるのは同意ページのみです。MCPリクエストには、発行済みのOAuthアクセストークンを使用する必要があります。

リバースプロキシの背後でMCP HTTPを提供する場合は、DNSリバインディング保護を有効にしたままにし、想定されるホスト名のみを許可してください。

Docker を使った OpenAPI ブリッジ

OpenAPIモードはDockerのデフォルトのランタイムであり、APIキーが必要です：

export PROXMOX_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8811:8811 \
  -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

OpenAPIのインターフェースを確認します：

curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json

認証なしのローカル開発に限り、PROXMOX_ALLOW_NO_AUTH=trueを設定してください。

ソースコードのチェックアウト

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"
python main.py

8811サービスはOpenAPI/RESTブリッジです。8000サービスはネイティブのMCP HTTPエンドポイントです。

クライアントのインストール

クライアントがMCPインストール用ディープリンクに対応している場合はワンクリックボタンを使用するか、以下のJSON設定をコピーしてください。

推奨するstdio設定：

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

クライアント設定に認証情報を保存したくない場合は、ローカル設定ファイルを使用してください。

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
      }
    }
  }
}

Claude Desktop、Cursor、VS Code、Codex、OpenCode、Open WebUI、Streamable HTTP、OpenAPI向けのクライアント別の例は、クライアント設定ガイドおよび統合ガイドにあります。

デモ

このデモは、ローカルのProxmoxラボに対して英語でライブMCPセッションを操作するqwen/qwen3.6-plusを直接録画したターミナル記録です。自然言語による操作がMCPツールを通じて実行され、LXCの作成と起動、コンテナコマンドの実行、認証が必要なHTTP /healthエンドポイントの確認まで行う様子を示しています。

MP4版を見る

適切なツールを選ぶ

まず読み取り専用の調査から始め、対象ノード、ストレージ、VMID、権限が明確になってから、状態を変更するツールを使用してください。

オペレーターの目的	最初に使用するツール	次に使用するツール	備考
クラスターを調査する	get_nodes、get_cluster_status	get_storage、get_vms、get_containers	クライアントのインストール後、最初に行うヘルスチェックに最適です
VM を作成または管理する	get_nodes、get_storage	create_vm、start_vm、stop_vm、delete_vm	長時間実行される変更処理は、job_id と Proxmox の task_id を返します
LXC を管理する	get_containers、get_storage	create_container、start_container、stop_container、delete_container	SSH を使用するコマンドツールには、オプションの ssh 設定が必要です
リスクのある変更をロールバックする	vm_type=qemu または vm_type=lxc を指定して list_snapshots	create_snapshot、rollback_snapshot、delete_snapshot	破壊的なワークフローのテストを行う前にスナップショットを作成してください
ゲスト内でコマンドを実行する	VM またはコンテナーのステータスツール	execute_vm_command、execute_container_command	VM の場合は QEMU Guest Agent が必要です。LXC の場合は Proxmox ノードへの SSH 接続が必要です
非同期処理を追跡する	job_id を含む変更処理の応答	poll_job、get_job、list_jobs、retry_job、cancel_job	エージェントやユーザーとのやり取りには job_id を使用し、Proxmox の生の追跡には task_id を使用してください
ログを調査する	get_node_syslog、get_cluster_log	get_task_log、get_node_firewall_log、get_guest_firewall_log	すべてのログツールは読み取り専用です。get_task_log は任意の Proxmox UPID を受け付けます
HTTP ツールから自動化する	/openapi.json	/jobs、/health、生成されたツールルート	Bearer 認証を使用し、ローカル開発以外では CORS を制限してください

ツールの全体像については、ツール選択ガイドとAPI とツールのリファレンスを参照してください。

セキュリティモデル

ProxmoxMCP-Plus はアクセスレイヤーであり、Proxmox RBAC、ネットワーク制御、クライアント側の MCP 承認プロンプトに代わるものではありません。

このプロジェクトでは、オペレーターが利用できる制御ポイントをいくつか提供しています。

• Proxmox API トークンによって、バックエンドが実行できる操作が決まります。
• PROXMOX_API_KEY は、デフォルトで OpenAPI ブリッジを保護します。
• MCP_API_KEY は、ネイティブの Streamable HTTP と SSE を Bearer 認証で保護します。MCP_ALLOW_UNAUTHENTICATED_HTTP=true を明示してアクセス制御を委任しない限り、この設定は必須です。
• 開発モードを明示的に有効にしない限り、TLS 検証が適用されます。
• command_policy は、コマンドの実行と高リスク操作を制御します。
• approval_token を使うと、コマンドの実行と高リスクな変更操作を承認制にできます。
• MCP Streamable HTTP のデプロイでは、DNS リバインディング保護に加えて、Host と Origin の許可リストを使用できます。
• オプションの MCP ツール許可リストまたは拒否リストを使うと、実行時に公開するツールを制限できます。ただし、これらは Proxmox RBAC の代わりにはなりません。
• ログでは、コマンドや認証情報が漏えいしないように設計されています。

信頼できるローカル環境の外部にサーバーを公開する前に、セキュリティガイドをお読みください。

コアプラットフォーム機能

ProxmoxMCP-Plus は、Proxmox VE で多くのチームが実際に必要とする運用タスクを、統一された操作窓口から実行できます。同じサーバーから、LLM や AI エージェントのユースケース向けに MCP クライアントへ、また OpenAPI ブリッジを介して HTTP クライアントへ、これらのワークフローを提供できます。

対応するワークフロー領域：

機能領域	利用可否
VM の作成／起動／停止／削除	利用可能
VM スナップショットの作成／ロールバック／削除	利用可能
バックアップの作成／復元	利用可能
ISO のダウンロード／削除	利用可能
LXC の作成／起動／停止／削除	利用可能
コンテナーでの SSH を使用したコマンド実行	利用可能
コンテナーの authorized_keys の更新	利用可能
長時間実行タスク向けの永続ジョブストア	利用可能
MCP ジョブ制御ツール（list_jobs、get_job、poll_job、cancel_job、retry_job）	利用可能
明示的なステータスコードを返す OpenAPI /jobs エンドポイント	利用可能
ローカル OpenAPI の /livez、/readyz、/health、スキーマ	利用可能
/mcp での Docker ネイティブ MCP Streamable HTTP	利用可能
Docker イメージのビルドと /livez	利用可能

このリポジトリで検証やコントラクトの確認に使用できるエントリーポイント：

• python -m pytest -q（CI のカバレッジゲート全体については、コントリビューションを参照してください）
• ruff check .
• mypy src --ignore-missing-imports
• python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
• tests/integration/test_real_contract.py
• tests/scripts/run_real_e2e.py

tests/scripts/run_real_e2e.py は、proxmox-config/config.live.json または PROXMOX_MCP_E2E_CONFIG を優先するようになりました。 これにより、マシン固有のデフォルト設定である config.json を使って、ライブチェックを誤って実行することを防げます。

長時間実行ジョブ

Proxmox の変更操作の多くは非同期です。ProxmoxMCP-Plus は、これらのタスクを永続ジョブレイヤーでラップするようになりました。これにより、MCP クライアントと OpenAPI クライアントは、安定した Job ID を使ってタスクを追跡できます。

VM の作成／起動／停止、コンテナーの作成／起動／停止、スナップショットの変更、バックアップ／復元、ISO のダウンロード／削除などの長時間実行ツールは、次の両方を返すようになりました。

• task_id：Proxmox の生の UPID
• job_id：サーバー側の安定したジョブレコード

ジョブレコードには次の情報が保存されます。

• 現在のステータスと進捗状況
• 再試行回数と以前の UPID
• 最新の結果ペイロードまたは失敗理由
• 作成、ポーリング、再試行、キャンセルの監査履歴

デフォルトでは、ジョブストアは proxmox-jobs.sqlite3 に永続化されるため、再起動しても実行中または完了済みのジョブのメタデータは失われません。

監査イベントは、別の SQLite テーブルに追記されます。既存の履歴は起動時に移行され、API の audit_log 形式は変更されません。デフォルトでは保持期間に制限はありません。イベントの有効期限切れを起動時および各ジョブの更新時に削除するには、JSON 設定で jobs.audit_retention_days に正の数を設定してください。この設定によってジョブ自体が削除されることはありません。このアップグレードの前に、データベースを共有しているすべてのワーカーを停止し、データベースをバックアップしてください。同じデータベースに旧バージョンと新バージョンを同時に接続して実行しないでください。監査履歴を保持したままダウングレードする必要がある場合は、アップグレード前のバックアップを復元してください。

キャンセル要求は、タスクの完了を意味しません。retry_job を呼び出す前に、タスクが失敗またはキャンセル済みになるまでポーリングしてください。キャンセルが保留中のタスクは再試行できません。

MCP ジョブツール

• list_jobs
• get_job
• poll_job
• cancel_job
• retry_job

OpenAPI ジョブルート

OpenAPI プロキシが有効で、ローカルの JobStore が利用可能な場合、以下のルートが直接公開されます。

パス	メソッド	用途	成功コード
/jobs	GET	永続化されたジョブの一覧表示	200
/jobs/{job_id}	GET	1 件のジョブを取得します。refresh=true は任意です	200
/jobs/{job_id}/poll	POST	Proxmox からステータスを更新します	200
/jobs/{job_id}/cancel	POST	キャンセルをリクエストします	202
/jobs/{job_id}/retry	POST	保存された再試行レシピを再実行します	202

共通のエラーコード：

• 404：不明な job_id
• 409：ジョブは存在しますが、その操作は現在実行できません
• 503：ローカルの JobStore なしで OpenAPI プロキシが起動されました

tests/scripts/run_real_e2e.py は、proxmox-config/config.live.json または PROXMOX_MCP_E2E_CONFIG を優先するようになりました。 これにより、マシン固有のデフォルト設定である config.json に対して誤ってライブチェックを実行することを防ぎます。

一般的なアプローチとの比較

機能	公式 Proxmox API	単発スクリプト	ProxmoxMCP-Plus
LLM と AI エージェントのワークフロー向け MCP	いいえ	いいえ	はい
標準的な HTTP ツール向けの OpenAPI インターフェース	いいえ	通常はありません	はい
VM と LXC の操作を単一のインターフェースで実行	低レベルのみ	場合によります	はい
スナップショット、バックアップ、復元のワークフロー	低レベルのみ	場合によります	はい
非同期ジョブの永続的な追跡と再試行	いいえ	まれです	はい
ポリシー制御付きコンテナコマンドの実行	いいえ	カスタム実装のみ	はい
Docker による配布手段	いいえ	まれです	はい
リポジトリレベルでのライブ環境検証	該当なし	まれです	はい

シナリオテンプレート

すぐにコピーして使えるサンプルは docs/examples/ にあります。

• テスト VM の作成
• スナップショットを使ってリスクのある変更をロールバック
• ISO をダウンロードして LXC を作成

これらは、人間のオペレーターと LLM 主導の利用の両方を想定して作成されています。

ドキュメント

README は、GitHub で素早く内容を把握できるよう意図的に最適化されています。より詳しい運用ドキュメントは docs/wiki/ にあり、GitHub Wiki に公開することもできます。

必要な情報	参照先
プロジェクトとデプロイの流れを理解する	Wiki ホーム
Proxmox 環境向けに設定して実行する	オペレーターガイド
Claude Desktop、Cursor、VS Code、Codex、Open WebUI、または HTTP クライアントを接続する	クライアント設定ガイド
ワークフローに適したツールを選ぶ	ツール選択ガイド
ドキュメント品質の目標、メディア計画、公開チェックリストを確認する	ドキュメント品質計画
統合パターンとトランスポートの詳細を確認する	統合ガイド
MCP 対応 IDE とエージェントからインストールする	エージェントのインストール
SSH 経由の LXC コマンド実行を有効にする	コンテナコマンドの実行
セキュリティとコマンドポリシーを確認する	セキュリティガイド
ツールのパラメーター、前提条件、動作を確認する	API とツールのリファレンス
起動、認証、ヘルスの問題をデバッグする	トラブルシューティング
コードベースの作業やリリースを行う	開発者ガイド
リリースとアップグレードに関する注意事項を確認する	リリースとアップグレードに関する注意事項

公開済み Wiki：

• GitHub Wiki ホーム

リポジトリの構成

• src/proxmox_mcp/：MCP サーバー、設定の読み込み、セキュリティ、OpenAPI ブリッジ
• main.py：ローカル利用およびクライアント主導の利用における MCP のエントリーポイント
• docker-compose.yml：HTTP/OpenAPI ランタイム
• requirements/：補助的な依存関係ソースとランタイムのインストールリスト
• scripts/：ローカルワークフロー用の起動補助スクリプト
• tests/scripts/run_real_e2e.py：実環境の Proxmox と Docker/OpenAPI の経路
• tests/：単体テストおよび統合テストのカバレッジ
• docs/examples/：シナリオに基づくプロンプトと HTTP の例
• docs/wiki/：運用、統合、リファレンスに関する詳細なドキュメント

開発時のチェック

環境設定、テストの前提条件、プルリクエストのガイダンスについては、 Contributing を参照してください。

python -m pytest -q
ruff check .
mypy src --ignore-missing-imports
python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
python -m build

CI では PostgreSQL を使用したテストも実行され、ランタイムのステートメントカバレッジ全体と 重要なモジュールのブランチカバレッジ全体が必須となります。正確なカバレッジコマンドについては Contributing を、レビュー済みのランタイムロックのワークフローについては Dependency updates を参照してください。

コミュニティ

• 貢献方法
• 行動規範
• アクセシビリティ
• セキュリティポリシー
• 問題を報告
• ディスカッション

ライセンス

MIT

ISO のインストールと LXC ネットワーク設定

list_isos を使って既存の ISO ボリュームを検索します（または download_iso を使って取得します）。 create_vm は iso_volume="local:iso/debian.iso" を受け付け、デフォルトでこれを ide3 にマウントし、ディスクより先に CD-ROM から起動します。update_vm_config を使うと、 ISO をマウントまたは変更したり、iso_volume="none" で取り外したり、boot_order="scsi0;ide3" を設定したり、 MAC/VLAN/ファイアウォールの設定を保持したまま net0 の network_bridge を変更したりできます。空きのある cdrom_device を選択してください。既存のデータディスクと cloud-init ドライブは置き換えられません。 メディアとブリッジの編集では現在の設定を読み取るため、関連する設定権限に加えて VM.Audit が必要です。既存のサイズ変更や cloud-init のみの更新では、引き続き事前の読み取りは不要です。

LXC ではインストーラー ISO ではなく、OS テンプレートを使用します。create_container はデフォルトで DHCP を維持し、新たに network_bridge、ip="192.168.1.50/24"、gw="192.168.1.1"、ip6、 gw6 を受け付けます。update_container_network は既存のインターフェース（デフォルトは net0、 net31 まで選択可能）でこれらのフィールドを編集し、指定されていないオプションをすべて保持します。 ゲートウェイを削除するには空の文字列を指定します。DHCP と手動設定を切り替えると、そのアドレスファミリーの 既存のゲートウェイが削除されます。ネットワークの変更によってゲストの接続が中断する可能性があります。 どちらの編集ツールも、名前付きターゲット、読み取り専用、高リスクの承認ポリシーに従います。 カスタムの高リスクリストと必要なツールの許可リストに update_container_network を追加してください。 アップグレードの詳細については、v0.5.19 リリースノート を参照してください。