proxmox-mcp
proxmox-mcp
Proxmox VE向けのDockerファーストなModel Context Protocol (MCP) サーバーです。
読み取り専用のクラスター検査、VM/コンテナのライフサイクル操作、スナップショット、移行、プロビジョニング支援、および安全な確認ゲートを備えた汎用Proxmox APIエスケープハッチのための、安全で構造化されたツールを提供します。
ステータス
アルファ版。APIトークン認証と、変更を伴う操作に対する明示的な確認ゲートを備えています。
Related MCP server: Proxmox MCP Server
Docker Composeでの実行
Docker Composeは、このMCPサーバーを実行するための主要な推奨方法です。
cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --buildデフォルトでは、MCPサーバーは以下でリッスンします:
http://127.0.0.1:8000/mcp.env.exampleにおけるデフォルトのMCPトランスポート設定:
MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcpDocker内部では、アプリはコンテナ内の 0.0.0.0 にバインドされますが、Composeはデフォルトでホストのループバック上でのみ公開します:
ports:
- "127.0.0.1:8000:8000"この認証されていないMCPエンドポイントを、適切なネットワーク制御を前面に配置せずにすべてのインターフェースで公開しないでください。
サポートされているMCPトランスポート:
streamable-http— Dockerおよびほとんどのリモートデプロイメントのデフォルトsse— レガシーなHTTP/SSE MCPトランスポートstdio— ローカルサブプロセスモード
MCPエンドポイントをHTTPSで公開する場合は、Caddy、Traefik、nginxなどのリバースプロキシをこのサービスの前に配置し、そこでTLSを終端してください。特別な理由がない限り、コンテナ内部はプレーンなHTTPのままにしてください。
Proxmoxプロトコル設定
Proxmox APIにはHTTPSを推奨します:
PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certs意図的にProxmoxでプレーンなHTTPが必要な場合は、明示的に指定してください:
PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=trueプレーンなHTTPはネットワーク経由で資格情報を送信します。これは、厳密に制御されたラボネットワーク以外では通常避けるべきです。
認証
Proxmox APIトークンを推奨します:
PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-meパスワードチケット認証もサポートされていますが、MCPにはAPIトークンの方がクリーンです:
PVE_USERNAME=user@pam
PVE_PASSWORD=replace-meDocker HTTP MCP用のHermes設定
mcp_servers:
proxmox:
url: "http://127.0.0.1:8000/mcp"
timeout: 120
connect_timeout: 30TLSの背後にあるリモートホストにデプロイする場合:
mcp_servers:
proxmox:
url: "https://proxmox-mcp.example.internal/mcp"
timeout: 120
connect_timeout: 30Dockerなしでの実行
ローカルのstdioモードは開発用に引き続き利用可能です:
MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcpDockerなしでのローカルHTTPモード:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcp安全性モデル
GETリクエストはデフォルトで許可されます。POST、PUT、およびDELETEにはconfirm=trueが必要です。高レベルのライフサイクル/プロビジョニングツールにも
confirm=trueが必要です。シークレットが意図的に返されることはありません。
汎用APIパスは、完全なURL、クエリ文字列、フラグメント、トラバーサル、エンコードされたトラバーサル、およびエンコードされたスラッシュのトリックを拒否します。
パスセグメントは、Proxmoxに送信される前に検証およびエンコードされます。
ツールカバレッジ
フェーズ1: 読み取り専用
pve_get_versionpve_get_cluster_statuspve_list_nodespve_list_resourcespve_list_vmspve_get_vm_statuspve_get_vm_configpve_list_storagepve_list_backupspve_get_task_statuspve_get_node_metrics
フェーズ2: 安全なアクション
pve_start_vmpve_shutdown_vmpve_stop_vmpve_reboot_vmpve_suspend_vmpve_resume_vmpve_create_snapshotpve_delete_snapshotpve_rollback_snapshotpve_migrate_vm
フェーズ3: 管理/プロビジョニング + エスケープハッチ
pve_clone_vmpve_create_lxcpve_create_qemu_vmpve_delete_vmpve_resize_diskpve_set_vm_configpve_api_request
開発
uv sync --extra dev
uv run pytest
uv run ruff check .Available Tools
28 toolspve_api_requestC
Call any Proxmox API path. GET is allowed; POST/PUT/DELETE require confirm=true.
Inputs: path (required), method (required), params, confirm. Returns: object
pve_clone_vmC
Clone a QEMU VM. Requires confirm=true.
Inputs: node (required), newid (required), source_vmid (required), full, +4 more. Returns: object
pve_create_lxcC
Create an LXC container. Requires confirm=true.
Inputs: node (required), vmid (required), storage (required), ostemplate (required), +8 more. Returns: object
pve_create_qemu_vmC
Create a QEMU VM. Requires confirm=true.
Inputs: node (required), vmid (required), ide2, name, +7 more. Returns: object
pve_create_snapshotB
Create a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +3 more. Returns: object
pve_delete_snapshotA
Delete a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
pve_delete_vmC
Delete a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), purge, confirm, +2 more. Returns: object
pve_get_cluster_statusA
Return Proxmox cluster status.
Inputs: no named parameters. Returns: object
pve_get_node_metricsC
Get node status and metrics.
Inputs: node (required). Returns: object
pve_get_task_statusC
Get task status by UPID.
Inputs: node (required), upid (required). Returns: object
pve_get_versionA
Return Proxmox VE version information.
Inputs: no named parameters. Returns: object
pve_get_vm_configA
Get config for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
pve_get_vm_statusB
Get current status for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
pve_list_backupsB
List backup content for a node storage.
Inputs: node (required), storage (required). Returns: object
pve_list_nodesA
List Proxmox nodes.
Inputs: no named parameters. Returns: object
pve_list_resourcesB
List cluster resources, optionally filtered by type such as vm, storage, node.
Inputs: resource_type. Returns: object
pve_list_storageA
List storage globally or for a node.
Inputs: node. Returns: object
pve_list_vmsA
List QEMU VMs and LXC containers from cluster resources.
Inputs: no named parameters. Returns: object
pve_migrate_vmB
Migrate a VM/container to another node. Requires confirm=true.
Inputs: node (required), vmid (required), target (required), online, +4 more. Returns: object
pve_reboot_vmA
Reboot a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_resize_diskC
Resize a QEMU VM disk. Requires confirm=true.
Inputs: disk (required), node (required), size (required), vmid (required), +1 more. Returns: object
pve_resume_vmB
Resume a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_rollback_snapshotC
Rollback to a snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
pve_set_vm_configC
Update VM/container config. Requires confirm=true.
Inputs: node (required), vmid (required), config (required), confirm, +1 more. Returns: object
pve_shutdown_vmB
Gracefully shut down a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, timeout, +2 more. Returns: object
pve_start_vmC
Start a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_stop_vmA
Hard stop a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_suspend_vmC
Suspend a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target a distinct resource/action combination, and lifecycle verbs like start, shutdown, stop, and reboot are clear. The main ambiguity comes from the overlapping read-only listing tools (list_resources, list_vms, list_nodes, list_storage), though the descriptions help differentiate them. pve_api_request is a deliberate escape hatch rather than a source of confusion.
All tools follow a consistent pve_verb_noun snake_case pattern. Verbs are predictable: list/get for reads, create/delete/set for mutations, and explicit lifecycle verbs for VM/container actions. There are no mixed naming conventions or vague generic names.
28 tools exceeds the 25+ threshold and feels heavy for a single server. Several listing and config tools could be consolidated, and the generic pve_api_request already provides broad fallback coverage. The domain is broad but the surface is larger than necessary.
Core VM/container lifecycle, snapshot management, migration, cloning, creation, deletion, config updates, and disk resize are covered. Notable gaps like LXC clone/resize and advanced storage/network management are not directly exposed, but pve_api_request provides a workaround. The surface has no critical dead ends.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for Product Management
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.109 npm2MIT
- AlicenseCqualityCmaintenanceA comprehensive MCP server providing 92 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.92190 npm6MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for full Proxmox VE management - VMs, containers, storage, backups, networking.2MIT
- AlicenseBqualityCmaintenanceAn MCP server that exposes Proxmox VE node/cluster as tools for MCP clients, enabling management of VMs and containers including power control, resource reconfiguration, snapshots, and backups.20MIT