Proxmox-mcp

Name: proxmox-mcp
Author: akmalovaa

Release License: MIT Python 3.14 GHCR MCP

간단한 Proxmox MCP

Proxmox VE 관리를 위한 MCP 서버

38개의 도구 — 노드, QEMU VM, LXC 컨테이너, 스토리지, 클러스터, 스냅샷.

왜 이 도구인가요?

단일 이미지, 다중 아키텍처 지원 — docker run ghcr.io/akmalovaa/proxmox-mcp:latest 명령어로 즉시 실행 가능
환경 변수만 사용 — 설정 파일, 데이터베이스, 상태 저장 없음
기본적으로 읽기 전용 — 파괴적인 작업은 명시적인 PROXMOX_RISK_LEVEL 설정을 통해서만 가능
작은 코드베이스 — Proxmoxer 기반의 순수 stdio MCP, HTTP 서버나 인증 계층, 불필요한 기능 없음
원시 JSON 출력 — 서식이나 이모지 없이 LLM이 데이터를 직접 처리 가능

빠른 시작

이미지: ghcr.io/akmalovaa/proxmox-mcp:latest (다중 아키텍처: amd64 + arm64).

1. 셸 프로필(~/.zprofile, ~/.zshrc 또는 ~/.bashrc)에 자격 증명 내보내기:

# base environment:
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_PASSWORD=your-password

# or use token auth (recommended):
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# optional:
export PROXMOX_RISK_LEVEL=read

적용: source ~/.zprofile (또는 셸 재시작).

2. ~/.claude/settings.json (Claude Code) 또는 claude_desktop_config.json (Claude Desktop)에 추가:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

또는 토큰 인증:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

값이 없는 docker run -e VAR는 호스트 변수를 그대로 전달하므로 설정 파일에 비밀 정보가 노출되지 않습니다. 클라이언트를 재시작하면 38개의 Proxmox 도구를 사용할 수 있습니다.

비밀번호 인증을 사용하려면 토큰 변수 대신 PROXMOX_PASSWORD를 사용하세요.

참고: macOS의 Claude Desktop은 launchd를 통해 실행되며 ~/.zprofile/~/.zshrc를 상속받지 않습니다. 설정을 ~/.zshenv에 넣거나 설정 파일 내의 "env": { ... } 블록을 사용하세요.

설정

모든 설정은 환경 변수입니다. 셸 프로필에 설정하거나, docker run -e에 인라인으로 전달하거나, MCP 클라이언트의 env 블록에 선언하세요.

변수	기본값	설명
`PROXMOX_HOST`	—	Proxmox 호스트 (IP 또는 호스트명)
`PROXMOX_USER`	`root@pam`	API 사용자
인증	—
`PROXMOX_PORT`	`8006`	API 포트
`PROXMOX_VERIFY_SSL`	`false`	TLS 인증서 검증
`PROXMOX_RISK_LEVEL`	`read`	`read` / `lifecycle` / `all`

인증: 토큰 또는 비밀번호

하나만 선택하세요. 둘 다 설정된 경우 토큰이 우선합니다.

토큰 (권장) — Proxmox UI에서 생성: 데이터센터 → 권한 → API 토큰 → 추가 (권한 분리 체크 해제). 그 후:

export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

비밀번호 (대체 수단):

export PROXMOX_PASSWORD=your-password

위험 수준

PROXMOX_RISK_LEVEL은 파괴적인 작업을 제어합니다:

수준	추가 기능
`read` (기본값)	읽기 전용 도구
`lifecycle`	+ 시작 / 중지 / 재부팅 / 일시 중지 / 복제 / 스냅샷 생성
`all`	+ 스냅샷 삭제 / 스냅샷 롤백

모든 권한이 필요한 호출은 stderr에 기록됩니다 (ALLOW / DENY + 도구 + 계층).

도구

노드 (7)

도구	설명
`list_nodes`	상태, CPU, 메모리, 가동 시간을 포함한 모든 클러스터 노드 나열
`get_node_status`	상세 노드 메트릭 (CPU, 메모리, 디스크, 부하, 커널)
`get_node_networks`	노드의 네트워크 인터페이스
`get_node_disks`	노드의 물리적 디스크
`get_node_tasks`	노드의 최근 작업
`get_task_status`	UPID로 특정 작업 상태 확인
`get_task_log`	작업의 로그 출력

QEMU VM (14)

도구	계층	설명
`list_vms`	read	모든 VM 나열 (노드별 필터링 가능)
`get_vm_status`	read	현재 VM 상태 (실행 중/중지됨, CPU, 메모리)
`get_vm_config`	read	VM 설정 (하드웨어, 디스크, 네트워크)
`list_vm_snapshots`	read	VM의 모든 스냅샷 나열
`start_vm`	lifecycle	VM 시작
`stop_vm`	lifecycle	VM 강제 중지
`shutdown_vm`	lifecycle	타임아웃을 포함한 정상적인 ACPI 종료
`reboot_vm`	lifecycle	ACPI를 통한 재부팅
`suspend_vm`	lifecycle	VM 일시 중지
`resume_vm`	lifecycle	일시 중지된 VM 재개
`clone_vm`	lifecycle	전체 또는 링크된 복제
`create_vm_snapshot`	lifecycle	스냅샷 생성
`delete_vm_snapshot`	all	스냅샷 삭제
`rollback_vm_snapshot`	all	스냅샷으로 롤백

LXC 컨테이너 (11)

도구	계층	설명
`list_containers`	read	모든 LXC 컨테이너 나열 (노드별 필터링 가능)
`get_container_status`	read	현재 컨테이너 상태
`get_container_config`	read	컨테이너 설정
`list_container_snapshots`	read	모든 스냅샷 나열
`start_container`	lifecycle	컨테이너 시작
`stop_container`	lifecycle	컨테이너 강제 중지
`shutdown_container`	lifecycle	타임아웃을 포함한 정상적인 종료
`reboot_container`	lifecycle	컨테이너 재부팅
`create_container_snapshot`	lifecycle	스냅샷 생성
`delete_container_snapshot`	all	스냅샷 삭제
`rollback_container_snapshot`	all	스냅샷으로 롤백

스토리지 (2)

도구	설명
`list_storage`	사용량을 포함한 스토리지 풀 나열 (노드별 필터링 가능)
`get_storage_content`	스토리지 풀의 콘텐츠 (ISO, 백업, 이미지, 템플릿)

클러스터 (4)

도구	설명
`get_cluster_status`	클러스터 상태, 쿼럼, 노드 멤버십
`get_cluster_resources`	모든 리소스 (VM, 컨테이너, 스토리지, 노드)
`get_cluster_backups`	설정된 백업 작업
`get_next_vmid`	다음 사용 가능한 VM/컨테이너 ID

아키텍처

src/proxmox_mcp/
├── server.py    # FastMCP instance + entry point
├── config.py    # Pydantic Settings (PROXMOX_ prefix)
├── client.py    # Proxmoxer connection via lifespan
└── tools/       # nodes, vms, containers, storage, cluster

기본적으로 읽기 전용 — 권한이 필요한 도구는 PROXMOX_RISK_LEVEL로 제어
단일 연결 — 시작 시 Proxmoxer 클라이언트가 한 번 생성되어 수명 주기 동안 공유됨
원시 JSON 출력 — 서식 없음; LLM이 데이터를 직접 소비

개발

독립 실행형 실행 (테스트)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

Docker 없이 실행 (UV)

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

MCP 클라이언트 설정:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

소스에서 빌드

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

라이선스

MIT

proxmox-mcp