proxmox-ve-mcp

하나 이상의 Proxmox VE 호스트를 LLM 클라이언트가 호출할 수 있는 도구로 노출하는 MCP 서버입니다. 인벤토리 노드, 게스트, 스토리지 및 네트워크 브리지를 조회하고, 실시간 상태를 읽으며, VM과 컨테이너를 생성, 복제, 시작, 중지 및 삭제할 수 있습니다.

Streamable HTTP를 통해 MCP를 사용하므로, 단일 클라이언트의 로컬 하위 프로세스가 아닌 네트워크 상의 자체 서비스로 실행됩니다.

universal-network-director를 위해 구축되었습니다. 이는 모든 쓰기 작업에 사람의 승인 게이트가 있는 채팅 기반의 다중 벤더 네트워크 관리자입니다. 하지만 이 서버는 독립형 MCP 서버이며 모든 MCP 클라이언트와 함께 작동합니다.

Proxmox Server Solutions GmbH와 제휴, 보증 또는 지원되지 않습니다. "Proxmox" 및 "Proxmox VE"는 해당 소유자의 상표이며, 이 소프트웨어가 통신하는 대상을 설명하는 용도로만 사용됩니다.

프로덕션에 적용하기 전에 읽어보세요

24개의 도구 중 12개는 상태를 변경하며, 이 서버는 실행 전에 묻지 않습니다. 확인이나 드라이런이 없습니다. 모델이 호출하기로 결정하면 그대로 실행됩니다.

이를 처리하는 세 가지 방법, 실제로 도움이 되는 순서대로:

1. Proxmox API 토큰을 읽기 전용으로 범위 지정. 이것이 실제 제어이며, 이 코드가 아닌 Proxmox에 있습니다. 토큰에 / 경로에 내장된 PVEAuditor 역할을 부여하면 모델이 무엇을 결정하든 모든 쓰기 도구가 API에서 실패합니다. 쓰기 작업이 작동하도록 의도하지 않는 한 이렇게 하십시오.

2. 보호된 게스트 거부 목록 사용. config/protected-vms.json은 쓰기 도구가 건드리지 말아야 할 게스트를 나열하며, 백엔드 호출 전에 로컬에서 확인됩니다. 따라서 사람이 실수로 승인해도 유지됩니다. 파일이 없거나 구문 분석할 수 없으면 모든 게스트 쓰기를 거부하며, 아무것도 보호하지 않는 상태로 조용히 넘어가지 않습니다. 아래 참조.

3. 클라이언트에서 쓰기 게이트. 모든 상태 변경 도구는 write_ 접두사가 붙습니다. 이 접두사는 클라이언트가 이를 일치시키고 실행 전에 사람 승인 단계를 거치도록 라우팅할 수 있도록 하기 위한 이 코드베이스의 규칙입니다. 이 서버는 의도적으로 자체적으로 수행하지 않습니다 — 물어볼 사용자가 없기 때문입니다.

MCP 엔드포인트에 인증이 없습니다

이 서버는 포트에 도달할 수 있는 모든 사람에게 도구를 노출합니다. 토큰, 클라이언트 인증, MCP 측 TLS가 없습니다.

MCP_HOST는 이러한 이유로 기본값이 127.0.0.1입니다. 컨테이너 이미지는 0.0.0.0으로 설정하는데, 이는 필수적이므로 컨테이너의 포트를 게시하면 해당 인터페이스에 하이퍼바이저에 대한 인증되지 않은 제어 평면이 노출됩니다. 클라이언트와 함께 내부 네트워크에 두거나, 앞단에서 TLS 및 인증을 종료하십시오.

다중 호스트 설계

Proxmox 클러스터는 하나의 API를 공유하지만, 많은 설정이 클러스터 없이 다른 서브넷에서 여러 독립형 호스트를 실행합니다. 이 서버는 짧은 자유 형식 레이블로 키가 지정된 호스트당 하나의 연결을 유지하며, 모든 도구는 해당 레이블을 사용하여 통신할 호스트를 선택합니다.

호스트는 한 쌍의 환경 변수로 정의됩니다:

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

PROXMOX_<LABEL>_URL의 <LABEL>은 소문자로 변환되어 도구가 사용하는 host 값이 됩니다 (위의 server1). 세 번째 호스트를 추가하려면 세 번째 쌍을 추가하면 됩니다 — 코드 변경 없음. 사이트 이름을 지정하여 모델과 로그가 명확하게 읽히도록 하십시오.

토큰은 전체 user@realm!tokenid=secret 문자열이며, 생성 시 Datacenter → Permissions → API Tokens에서 한 번 표시됩니다. 인증은 상태 비저장입니다: 모든 요청은 Authorization: PVEAPIToken=... 헤더를 전달합니다. 로그인 호출이나 CSRF 토큰이 없습니다 — 이는 의도적으로 사용하지 않는 사용자 이름/비밀번호 세션 경로입니다.

자체 서명 인증서가 있는 호스트의 경우 PROXMOX_VERIFY_TLS=false로 설정하십시오. 기본값은 켜짐입니다.

보호된 게스트 거부 목록

config/protected-vms.json은 컨테이너에 읽기 전용으로 마운트되며, 쓰기 도구가 절대 건드리지 말아야 할 게스트를 보유합니다:

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

host는 Proxmox 노드 이름이 아닌 list_hosts의 레이블입니다. reason은 거부 메시지에 그대로 표시되므로, 이를 접하는 사람을 위해 작성하십시오.

이 파일은 git에서 추적되도록 설계되었습니다. 처음에는 추적되지 않는 .env의 환경 변수로 시작했는데, 이는 보호가 새 클론에서 유지되지 않고 빈 목록이 채워진 목록과 정확히 동일하게 보였기 때문입니다. 이제 파일이 없거나 구문 분석할 수 없으면 모든 게스트 쓰기를 거부합니다. 빈 목록은 허용되지만 시작 시 큰 경고를 기록합니다.

여기에 제공된 항목은 예시입니다. 중요한 것을 가리키기 전에 교체하십시오.

실행

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

또는 pip install -r requirements.txt를 virtualenv에 설치하고 python server.py를 직접 실행하십시오.

테스트

독립형 스크립트, pytest 없음. 컨테이너에서 실행하여 클라이언트가 필요로 하는 PROXMOX_* 환경을 갖추도록 하십시오:

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

오프라인 섹션은 가짜 인터페이스 및 게스트 목록을 사용하며 호스트가 구성되지 않은 상태에서 통과합니다. 라이브 섹션은 PROXMOX_* 변수가 가리키는 것을 읽으며, 아무것도 구성되지 않은 경우 깨끗이 건너뜁니다 — 실제 호스트를 가리켜서 가짜로 만들 수 없는 한 가지 구분(브리지가 업링크되었는지 격리되었는지)을 테스트하십시오.

설계 노트

• /cluster/resources가 인벤토리 백본입니다. 한 번의 호출로 모든 VM, 컨테이너, 노드 및 스토리지가 이미 노드, vmid 및 유형으로 태그되어 반환됩니다. 독립형 호스트에서도 작동합니다 (해당 노드 하나를 보고함). 따라서 노드별로 /nodes → /nodes/{node}/qemu를 탐색하는 대신 사용됩니다.

• list_network_bridges는 잘못된 브리지의 NIC가 도달할 수 없는 게스트를 만들기 때문에 존재합니다. 브리지별로 멤버 포트(박스 외부로 나가는 방법)가 있는지 또는 격리된 세그먼트인지 보고합니다. 이는 새 VM이 도달 가능한 상태로 시작되는지 여부를 결정하는 구분입니다.

• VLAN 태그는 실패 시 닫힙니다. bridge_vlan_aware가 아닌 브리지의 tag=는 Proxmox에서 수락된 후 조용히 전달되지 않습니다 — 격리가 요청된 곳에서 태그되지 않은 트래픽이 발생합니다. 쓰기 경로는 경고 대신 이를 거부하며, 확인을 위해 브리지 목록을 읽을 수 없으면 거부합니다.

• 쓰기는 비동기입니다. 대부분 Proxmox UPID를 반환합니다. 완료를 가정하지 말고 get_task_status로 폴링하십시오.

• 게스트 쓰기는 하나의 가드 뒤에서 실행됩니다. 단일 래퍼가 보호된 VM 확인과 vmid→노드/종류 확인을 수행하므로, 개별 도구가 가드를 잊거나 보호된 게스트에 대해 백엔드에 도달할 수 없습니다.

라이선스

Apache-2.0. LICENSE 참조.