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 전송.

Related MCP server: ProxmoxMCP

필수 권한

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

• 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

게시 흐름

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

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

14. 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 정당화가 필요합니다.

• 이 게이트가 충족될 때까지 작업은 커밋 준비가 된 것으로 간주되지 않습니다.

문서

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

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

• 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를 참조하십시오.