RekklesNA/ProxmoxMCP-Plus

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

전체 개요: ProxmoxMCP-Plus는 AI 어시스턴트(및 일반 HTTP 도구)가 Proxmox VE 가상화 서버를 운영할 수 있도록 하는 제어 계층입니다. VM 생성, Linux 컨테이너(LXC) 관리, 스냅샷 생성, 백업 실행, ISO 가져오기 등을 통합되고 보안을 고려한 인터페이스를 통해 수행할 수 있습니다. 운영자는 원시 Proxmox API 호출과 셸 스크립트를 직접 작성하는 대신, 이 서버를 한 번 설정하고 도구를 연결하기만 하면 됩니다.

해결하는 문제

Proxmox VE는 가상 머신과 컨테이너를 호스팅하는 기본 시스템입니다. 일반적으로 작업을 자동화하려면 원시 API 호출, 임시 스크립트, 사용자 지정 작업 폴링 루프를 조합해야 합니다. 이 프로젝트는 이러한 복잡한 방식을 두 가지 업계 표준 언어를 지원하는 단일 도구로 대체합니다.

MCP (Model Context Protocol): Claude Desktop, Cursor, VS Code, Open WebUI와 같은 AI 에이전트가 외부 도구와 통신하는 방식입니다. 이것이 "AI 클라이언트" 경로입니다.
OpenAPI (REST/HTTP): 기존 대시보드, 내부 스크립트 및 노코드 자동화 플랫폼이 서비스를 호출하는 방식입니다. 이것이 "표준 HTTP" 경로입니다.

두 경로 모두 동일한 워크플로우로 연결되므로 두 가지 다른 시스템을 배울 필요 없이 하나(또는 둘 다)를 사용할 수 있습니다.

실제 기능

README에 따르면 운영 범위는 다음과 같습니다:

VM 및 LXC 수명 주기 작업 — 가상 머신 및 컨테이너 시작, 중지, 생성, 삭제
스냅샷 — 생성, 롤백, 삭제
백업 및 복원 워크플로우
ISO 다운로드 및 정리 — 설치 이미지 가져오기 및 오래된 이미지 제거
노드, 스토리지 및 클러스터 검사 — 하이퍼바이저와 해당 환경의 상태 확인
SSH 기반 컨테이너 명령 — 가드레일이 있는 컨테이너 내에서 명령 실행(선택 사항, SSH 구성 필요)
선택적 보호 노드 SSH 명령 — Proxmox 호스트 자체에서 명령 실행(마찬가지로 보호되며 선택 사항)
지속적인 작업 추적 — 장기 실행 Proxmox 작업은 안정적인 작업 ID(job_id)를 얻고, Proxmox UPID를 추적하며, 폴링, 재시도, 취소 및 감사 기록을 지원합니다

실행 방법

README는 세 가지 주요 실행 경로를 제공합니다:

PyPI를 통한 MCP stdio — 로컬 AI 클라이언트(Claude Desktop, Cursor, VS Code)를 위한 클래식한 방법입니다. uvx proxmox-mcp-plus 또는 pip install proxmox-mcp-plus로 실행합니다.
Docker를 통한 네이티브 MCP HTTP — "Streamable HTTP" 전송을 지원하는 원격 MCP 클라이언트를 위한 방법입니다. 포트 8000의 /mcp에서 시작하며 MCP_API_KEY를 통한 API 키가 필요합니다.
Docker를 통한 OpenAPI 브리지 — 기본 Docker 모드로, 포트 8811에서 REST 엔드포인트를 제공하며 PROXMOX_API_KEY로 보호됩니다. 상태 확인 엔드포인트는 /livez, 사양은 /openapi.json에 있습니다.

이 중 하나를 실행하기 전에 Proxmox API 토큰을 생성하고 proxmox-config/config.example.json을 proxmox-config/config.json으로 복사한 후 호스트, 포트, 사용자 및 토큰 세부 정보를 입력해야 합니다. (선택적으로 ssh 및 jobs 섹션을 추가합니다.)

보안 기능

README는 "보안을 고려한" 설계를 강조합니다:

Proxmox용 API 토큰 (최소 권한)
OpenAPI 브리지용 Bearer 토큰 인증
명령 정책 — 허용되는 컨테이너/호스트 명령을 관리하는 규칙
승인 토큰 — 특정 작업에 대해 명시적인 사람의 승인을 요구할 수 있음
TLS 검증 — 기본적으로 SSL 인증서 검증
MCP HTTP 호스트/오리진 제어 — DNS 리바인딩 보호 및 허용된 오리진 목록
도구 노출 필터링 — 서버가 클라이언트에 보내는 도구 스키마를 제한하는 선택적 허용/거부 목록. 빈 목록은 모든 것을 비활성화하며, 알 수 없는 이름은 시작 실패를 유발하고, 정확한 소문자 이름만 작동합니다

코드 모드 (선택 사항)

기본적으로 서버는 전체 도구 카탈로그를 노출합니다. mcp.code_mode: true(또는 MCP_CODE_MODE=true)를 설정하면 세 가지 도구로 전환됩니다:

proxmox_code_search — 사용 가능한 도구 발견
proxmox_code_get_schema — 인수 스키마 가져오기
proxmox_code_execute — 도메인 도구에 대해 스크립트 식 실행

코드 실행은 격리된 샌드박스 내에서 실행되며(등록된 도구 호출 외에는 파일 시스템이나 네트워크 액세스 불가), 엄격한 제한이 있습니다: 64,000 소스 문자, 100MB 메모리, 25회 도구 호출, 16KB 최종 JSON, 2개 동시 실행, 30초 예산. 스크립트를 취소하거나 실패해도 도구의 부작용은 롤백되지 않습니다. 따라서 실패한 변경 사항을 자동으로 재시도해서는 안 됩니다. 선택적 작업자 풀 재사용이 가능합니다 (mcp.code_mode_pool_reuse).

OAuth 브라우저 게이트 (선택 사항, 네이티브 MCP HTTP)

원격 MCP 클라이언트를 위한 더 정교한 인증 흐름입니다. 원시 API 키를 보내는 대신 사용자는 PKCE(보안 로그인 표준)를 사용하는 OAuth 인증 코드 흐름을 거치며, 사람이 필요한 유일한 자격 증명은 MCP_API_KEY입니다. 브라우저는 동의 페이지를 방문하여 클라이언트가 원하는 것을 검토하고 키를 입력합니다. OAuth 상태는 (로컬 파일이 아닌) PostgreSQL에 저장되므로 여러 서버 인스턴스가 안전하게 상태를 공유할 수 있습니다. 서버는 프로토콜 엔드포인트에 MCP Python SDK를 사용하고 동의 페이지와 API 키 정책을 추가합니다.

MCP_OAUTH_ENABLED=true를 전환할 때의 주요 요구 사항: MCP_OAUTH_ISSUER(공용 HTTPS 오리진), MCP_OAUTH_DATABASE_URL(PostgreSQL DSN) 및 MCP_API_KEY. OAuth가 활성화되면 원시 Authorization: Bearer <key> 요청은 거부되며, 발급된 OAuth 토큰만 작동합니다.

차이점 (프로젝트 자체 표 기준)

우선순위	접근 방식
이중 액세스 경로	동일한 워크플로우에서 네이티브 MCP + OpenAPI
Proxmox 지향	기본을 넘어선 Day-2 운영: 스냅샷, 백업, ISO, 스토리지, 클러스터
장기 실행 작업	안정적인 작업 ID, UPID 추적, 폴링, 재시도, 취소, 감사 추적
더 안전한 실행	토큰, 명령 정책, 승인, TLS 검증, 호스트/오리진 제어
실제 검증	단위, 통합, Docker/OpenAPI 및 실시간 Proxmox 테스트(저장소에 문서화됨)

결론

Proxmox VE 클러스터를 운영하고 AI 에이전트나 HTTP 자동화로 안전하게 관리하고 싶다면, 이 프로젝트는 두 개의 인터페이스, 강력한 보안 태세, Proxmox의 비동기 작업을 위한 견고한 작업 추적 기능을 갖춘 설치 가능한 브리지를 제공합니다. JSON 파일과 환경 변수로 구성 가능하며, PyPI 또는 Docker에서 실행되고, 자율 에이전트가 인프라에 접근할 때 사용할 수 있는 완만한 가드레일(허용 목록, 승인, 샌드박스)이 포함되어 있습니다.