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비밀번호 티켓 인증도 지원되지만, API 토큰이 MCP에 더 깔끔합니다:
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