NANDI Proxmox MCP

Proxmox 클러스터를 자동화, 모니터링 및 제어된 실행을 위한 140개 이상의 도구를 갖춘 AI 기반 플랫폼으로 전환하세요.

NANDI Services에서 제공하는 Proxmox VE용 오픈 소스 MCP 서버입니다.

nandi-proxmox-mcp는 프로덕션 클러스터에 필요한 안전 장치를 제거하지 않으면서도 Proxmox 인벤토리, 수명 주기, 스토리지, 백업, 네트워킹, 방화벽, 액세스, 모니터링, SSH 진단 및 보호된 원격/컨테이너 작업을 노출합니다.

활성 상태 유지 항목

노드, 클러스터, QEMU, LXC, 스토리지, 백업, 작업, 네트워크, 방화벽, 풀, 액세스, 템플릿, 모니터링 및 원격 작업 전반에 걸친 140개 이상의 도구.
액세스 계층: read-only, read-execute, full.
모듈 분할: PVE_MODULE_MODE=core|advanced.
도구 필터: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
confirm=true를 통한 파괴적 작업 방지 가드레일.
listNodes, getVMStatus, startVM, stopContainer와 같은 하위 호환 별칭.
MCP 클라이언트를 위한 stdio 전송 및 제어된 원격 배포를 위한 스트리밍 가능한 HTTP 전송.

필수 권한

서버는 두 가지 신뢰 채널이 필요하며 두 채널 모두 의도적으로 유지됩니다:

Proxmox API 토큰
- 인벤토리, 수명 주기, 구성 및 관리 엔드포인트에 사용됩니다.
- ACL을 최소한으로 유지하세요: 실제로 활성화하는 도구에 필요한 역할만 부여하십시오.
Proxmox 호스트에 대한 SSH 배치 액세스
- pct exec, 배치 SSH 진단 및 컨테이너 수준 Docker 검사 도구에 필요합니다.
- Proxmox API 범위가 호스트 측 pct 및 SSH 기반 진단을 대체하지 않으므로 여전히 필요합니다.

자세한 내용: docs/PERMISSIONS.md

파괴적 작업 확인

파괴적으로 표시된 작업은 호출자가 confirm=true를 보내지 않으면 실행되지 않습니다.

예시:

VM/컨테이너 중지, 종료, 재부팅, 일시 중단, 삭제, 마이그레이션, 스냅샷 롤백
클러스터 상태를 변경할 수 있는 스토리지/네트워크/방화벽/액세스 쓰기 작업
pve_exec_in_container와 같은 고급 원격 실행

서버는 확인이 누락된 경우 구조화된 CONFIRMATION_REQUIRED 오류를 반환합니다. 이 동작은 변경되지 않았으며 강화되었습니다.

액세스 계층

read-only
- 인벤토리, 상태, 로그, 메트릭 및 비변경 진단.
read-execute
- 읽기 전용 및 선택된 실행/수명 주기 작업.
full
- 생성, 업데이트, 삭제, 마이그레이션, 복원 및 관리자 수준 작업.

PVE_MODULE_MODE=core는 코드베이스에서 표준 도구 ID를 이름 변경하거나 제거하지 않고 고급 도구를 숨깁니다.

런타임 구성

환경 변수

필수:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

선택 사항:

PROXMOX_PORT 기본값 8006
PROXMOX_SSH_PORT 기본값 22
PROXMOX_ALLOW_INSECURE_TLS 기본값 false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

HTTP 전송:

MCP_TRANSPORT=stdio|http
MCP_HOST 기본값 0.0.0.0
MCP_PORT 기본값 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

로컬 구성 파일

설정 시 .nandi-proxmox-mcp/config.json 및 .vscode/mcp.json이 작성됩니다.

구성 로더는 이제 다음을 거부합니다:

비어 있거나 잘못된 형식의 구성 경로
너무 큰 구성 파일
구성 경로의 제어 문자

빠른 시작

가이드 설정:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

환경 변수를 사용한 직접 실행:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

보안 모델 및 잔여 위험

이 MCP 서버는 실제 Proxmox 인프라를 운영하며 샌드박스 환경이 아닙니다.

신뢰 가정

서버는 신뢰할 수 있는 환경에 배포됨
승인된 운영자만 액세스 가능
네트워크 노출이 제어됨(공개적으로 노출되지 않음)
자격 증명이 안전하게 관리됨

잔여 위험

다음 위험은 시스템 설계에 내재되어 있습니다:

권한 있는 작업
전체 액세스 계층 및 컨테이너 실행 기능은 파괴적이거나 시스템 수준의 작업을 수행할 수 있습니다.
SSH 실행 경계
원격 명령 실행은 SSH에 의존하며 대상 시스템의 보안 상태를 상속합니다.
선택적 안전하지 않은 TLS 모드
활성화된 경우(PROXMOX_ALLOW_INSECURE_TLS=true), TLS 인증서 유효성 검사가 우회되어 MITM 공격에 연결이 노출될 수 있습니다. 실험실 용도로만 사용하십시오.
외부 종속성 동기화
패키지 배포 및 목록 가시성은 npm, MCP 레지스트리 및 마켓플레이스 전파 타이밍에 따라 달라집니다.

보안 책임

사용자는 다음 사항에 대한 책임이 있습니다:

신뢰할 수 있는 운영자로만 액세스 제한
최소 권한 API 토큰 및 SSH 키 사용
프로덕션 환경에서 안전하지 않은 TLS 사용 방지
기본 인프라를 적절하게 보호

구현된 안전 제어

액세스 계층(read-only, read-execute, full)
파괴적 작업에 대한 확인 필수
입력 유효성 검사 및 명령 강화
속도 제한 및 요청 유효성 검사

HTTP 강화

MCP_TRANSPORT=http가 활성화되면 서버는 다음을 적용합니다:

와일드카드 바인딩 보호를 포함한 호스트 허용 목록 적용
Origin 헤더를 보내는 요청에 대한 출처 유효성 검사
명시적 본문 크기 제한 및 정리된 413 응답
/mcp에 대한 속도 제한
요청/헤더/keep-alive 시간 초과
X-Content-Type-Options: nosniff
Cache-Control: no-store
스택 추적이 없는 정리된 오류 페이로드

상태/준비 엔드포인트:

GET /health
GET /ready
POST /mcp

SSH 및 명령 실행 강화

기능은 변경되지 않았지만 실행 경로는 더 엄격합니다:

로컬 명령 실행은 여전히 spawn(..., { shell: false })를 사용합니다.
SSH 호스트/사용자 값은 CLI 옵션을 몰래 포함할 수 없습니다.
SSH는 BatchMode, IdentitiesOnly, 공개 키 인증 및 명시적 연결 활성 제어를 사용합니다.
출력 버퍼는 무제한 메모리 증가를 방지하기 위해 제한됩니다.
dockerLogsInContainer는 이제 원시 사용자 입력을 보간하는 대신 컨테이너 이름을 검증하고 셸 이스케이프합니다.
임의의 컨테이너 명령 실행은 확인이 필요한 이미 파괴적인 pve_exec_in_container 흐름을 통해서만 계속 사용할 수 있습니다.

보안 상태

저장소의 완화 조치:

고정된 직접 종속성 버전 및 중요한 전이적 패키지에 대한 npm overrides
npm/패키지 스캐너를 위한 검증 가능한 패키지 메타데이터 및 저장소 링크
npm, 레지스트리 및 마켓플레이스 아티팩트를 위한 설명자/버전 동기화 검증
로그에서 토큰/헤더/비밀번호와 같은 값 삭제
클라이언트에 스택 추적이나 비밀이 반환되지 않음
린트, 타입 체크, 빌드, 테스트, 메타데이터 검증, 설명자 동기화, npm pack --dry-run 및 감사를 위한 CI 게이트

위협 모델 및 잔여 위험: docs/THREAT_MODEL.md

게시 흐름

릴리스 순서는 엄격합니다:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

태그 기반 release.yml은 이제 npm을 먼저 게시한 다음 MCP 레지스트리 설명자를 게시하여 동일한 버전에서 npm/레지스트리 드리프트를 방지합니다.

수동 폴백 및 문제 해결: docs/RELEASE.md

개발

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

문서 유지 관리 정책

이 저장소는 커밋 전 문서 동기화 게이트를 강제합니다.

change, fix 또는 refactor를 닫기 전에 README.md, AGENTS.md 및 CONTRIBUTING.md를 업데이트해야 하는지 평가하십시오.
문서가 동작 또는 프로세스 영향과 관련이 있는 경우 동일한 변경 세트에서 업데이트해야 합니다.
업데이트가 필요하지 않은 경우 명시적인 no-doc-change 정당화가 필요합니다.
이 게이트가 충족될 때까지 작업은 커밋 준비가 된 것으로 간주되지 않습니다.

문서

레지스트리 및 마켓플레이스

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
MCP 레지스트리: https://registry.modelcontextprotocol.io/
MCP 마켓플레이스 목록: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

라이선스

MIT. LICENSE를 참조하십시오.

nandi-proxmox-mcp