Skip to main content
Glama
proxmox-mcp

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=/mcp

Docker 내부에서 앱은 컨테이너의 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-me

Docker HTTP MCP를 위한 Hermes 구성

mcp_servers:
  proxmox:
    url: "http://127.0.0.1:8000/mcp"
    timeout: 120
    connect_timeout: 30

TLS 뒤의 원격 호스트에 배포된 경우:

mcp_servers:
  proxmox:
    url: "https://proxmox-mcp.example.internal/mcp"
    timeout: 120
    connect_timeout: 30

Docker 없이 실행

로컬 stdio 모드는 개발을 위해 계속 사용할 수 있습니다:

MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcp

Docker 없는 로컬 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_version

  • pve_get_cluster_status

  • pve_list_nodes

  • pve_list_resources

  • pve_list_vms

  • pve_get_vm_status

  • pve_get_vm_config

  • pve_list_storage

  • pve_list_backups

  • pve_get_task_status

  • pve_get_node_metrics

2단계: 안전한 작업

  • pve_start_vm

  • pve_shutdown_vm

  • pve_stop_vm

  • pve_reboot_vm

  • pve_suspend_vm

  • pve_resume_vm

  • pve_create_snapshot

  • pve_delete_snapshot

  • pve_rollback_snapshot

  • pve_migrate_vm

3단계: 관리/프로비저닝 + 이스케이프 해치

  • pve_clone_vm

  • pve_create_lxc

  • pve_create_qemu_vm

  • pve_delete_vm

  • pve_resize_disk

  • pve_set_vm_config

  • pve_api_request

개발

uv sync --extra dev
uv run pytest
uv run ruff check .

Available Tools

28 tools
pve_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

    B3.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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 npm
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An 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.
      20
      MIT