@itapi-core/mcp-proxmox

v2.0.0

Published

16 days ago

KR: Proxmox VE API 연동 MCP 서버. EN: MCP server for Proxmox VE operations over stdio and Streamable HTTP.

0High
0Medium
0Low

itapi

mcp proxmox pve virtualization mcp-server

Proxmox MCP Server (`@itapi-core/mcp-proxmox`)

Proxmox VE REST API를 통해 LLM이 노드 및 가상머신(QEMU/LXC), 스토리지, 네트워크 등을 포괄적으로 조회하고 제어할 수 있게 도와주는 Model Context Protocol (MCP) 서버입니다.

기능 (MCP Tools)

1. 가상머신 (VM / QEMU)

proxmox_list_vms: 노드의 VM 목록 조회
proxmox_create_vm: QEMU 가상머신 생성 (ISO, 디스크, 네트워크 포함)
proxmox_update_vm_config: VM 상세 설정(메모리, 코어 등) 핫플러그 변경
proxmox_resize_vm_disk: VM의 디스크 용량 증설
proxmox_change_vm_state: VM 전원 제어 (start/stop/reboot/suspend 등)
proxmox_delete_vm: VM 영구 삭제 (purge 옵션 포함)

2. 컨테이너 (LXC)

proxmox_list_lxc: 노드의 LXC 목록 조회
proxmox_create_lxc: LXC 컨테이너 생성 (rootfs, 네트워크, 비특권 컨테이너 포함)
proxmox_update_lxc_config: LXC 상세 설정 변경
proxmox_resize_lxc_disk: LXC의 디스크 용량 증설
proxmox_change_lxc_state: LXC 전원 제어
proxmox_delete_lxc: LXC 영구 삭제 (purge 옵션 포함)

3. 스냅샷 (Snapshot)

proxmox_list_vm_snapshots: VM 스냅샷 목록 조회
proxmox_create_vm_snapshot: VM 스냅샷 생성 (메모리 상태 포함 옵션)
proxmox_rollback_vm_snapshot: VM을 특정 스냅샷으로 복원
proxmox_delete_vm_snapshot: VM 스냅샷 삭제
proxmox_list_lxc_snapshots: LXC 스냅샷 목록 조회
proxmox_create_lxc_snapshot: LXC 스냅샷 생성
proxmox_rollback_lxc_snapshot: LXC를 특정 스냅샷으로 복원
proxmox_delete_lxc_snapshot: LXC 스냅샷 삭제

4. 모니터링 (Monitoring)

proxmox_get_cluster_status: 클러스터 전체 상태 및 리소스 요약
proxmox_get_node_status: 노드 CPU/메모리/디스크 사용률
proxmox_get_vm_status: VM 현재 전원 상태 및 리소스 사용률
proxmox_get_vm_config: VM 전체 설정(디스크, 네트워크, CPU 등) 조회
proxmox_get_lxc_status: LXC 현재 상태 및 리소스 사용률
proxmox_get_lxc_config: LXC 전체 설정 조회
proxmox_get_task_status: 비동기 태스크(UPID) 진행 상태 및 로그 조회
proxmox_list_node_tasks: 노드 최근 태스크 목록 (오류 필터 포함)

5. 클론 & 마이그레이션 (Clone & Migrate)

proxmox_clone_vm: VM 클론 생성 (전체 클론 / 연결 클론 선택)
proxmox_clone_lxc: LXC 클론 생성
proxmox_migrate_vm: VM을 다른 노드로 이동 (라이브 마이그레이션 지원)
proxmox_migrate_lxc: LXC를 다른 노드로 이동

6. 스토리지 (Storage)

proxmox_list_storage: 클러스터 내 연결된 스토리지 볼륨 조회
proxmox_create_storage: 신규 스토리지(NFS/LVM 등) 마운트 및 생성
proxmox_update_storage: 기존 스토리지 설정 변경
proxmox_delete_storage: 스토리지 마운트 제거

7. 스토리지 콘텐츠 (Storage Content)

proxmox_list_storage_content: 스토리지 내 콘텐츠(ISO, 템플릿, 이미지 등) 목록
proxmox_list_os_templates: LXC용 OS 템플릿 목록 조회
proxmox_list_iso_images: ISO 이미지 목록 조회
proxmox_delete_storage_content: 스토리지 내 특정 볼륨 삭제
proxmox_download_url: URL에서 직접 ISO/템플릿 다운로드

8. 네트워크 (Network)

proxmox_list_networks: 특정 노드의 네트워크 인터페이스 조회
proxmox_create_network: 브리지(Bridge), VLAN 등 신규 네트워크 인터페이스 생성
proxmox_update_network: 네트워크 인터페이스 설정(IP, Gateway 등) 변경
proxmox_delete_network: 인터페이스 삭제
proxmox_apply_network: 노드의 네트워크 설정 커밋(적용)

9. 노드 (Node)

proxmox_list_nodes: 클러스터 내 노드 조회
proxmox_node_service_cmd: 노드의 주요 시스템 서비스(예: pveproxy) 시작/재시작
proxmox_node_power_control: 노드 재부팅/셧다운

10. 범용 제어

proxmox_custom_request: GET 포함 모든 PVE API에 대한 범용 HTTP 통신

참고: 데이터 영구 손실을 초래할 수 있는 스토리지 포맷(Wipe) 등의 위험 기능은 API 수준에서 접근하지 않도록 제한되어 있습니다. 모든 기능은 **한국어(KR)**와 **영어(EN)**로 병기되어 제공됩니다.

실행 방법

로컬에서 npx를 사용하여 간편하게 실행할 수 있습니다.

인증 방법 (Authentication)

두 가지 인증 방식을 지원합니다.

방식 1: API 토큰 인증 (권장)

Proxmox API 토큰을 사용합니다. PROXMOX_TOKEN_ID와 PROXMOX_TOKEN_SECRET이 설정되면 자동으로 토큰 인증을 사용합니다.

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-proxmox"],
      "env": {
        "PROXMOX_URL": "https://pve.example.com:8006",
        "PROXMOX_TOKEN_ID": "root@pam!mytoken",
        "PROXMOX_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

API 토큰은 Proxmox 웹 UI의 Datacenter → Permissions → API Tokens 에서 생성할 수 있습니다.

방식 2: 비밀번호 인증

Proxmox 계정 비밀번호를 사용합니다. 로그인 Ticket을 자동으로 발급받으며, 만료 시 자동 재인증합니다.

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-proxmox"],
      "env": {
        "PROXMOX_URL": "https://pve.example.com:8006",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "yourpassword",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

환경 변수 (Environment Variables)

| 변수 | 필수 여부 | 설명 | |---|---|---| | PROXMOX_URL | 필수 | Proxmox VE 접속 주소 (예: https://pve.example.com:8006) | | PROXMOX_TOKEN_ID | 토큰 인증 시 필수 | API 토큰 ID (예: root@pam!mytoken) | | PROXMOX_TOKEN_SECRET | 토큰 인증 시 필수 | API 토큰 시크릿 | | PROXMOX_USER | 비밀번호 인증 시 필수 | Proxmox 계정 (예: root@pam) | | PROXMOX_PASSWORD | 비밀번호 인증 시 필수 | Proxmox 계정 비밀번호 | | NODE_TLS_REJECT_UNAUTHORIZED | 선택 | 0으로 설정 시 자체 서명된 SSL 인증서 경고를 무시합니다 (사내/내부망 권장) |