Skip to main content
Glama
deenesjakoruzh
akmalovaa

proxmox-mcp

by akmalovaa
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Proxmox-mcp

CI 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": { ... } 블록을 사용하세요.

Related MCP server: nandi-proxmox-mcp

설정

모든 설정은 환경 변수입니다. 셸 프로필에 설정하거나, 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

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
6Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • neverinfamous-memory-journal-mcp

    A MCP server built for developers enabling Git based project management with project and personal…

  • GitLab MCP Server

    Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.

  • better-notion-mcp

    Markdown-first MCP server for Notion API with 8 composite tools and 39 actions.

View all MCP Connectors

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/akmalovaa/proxmox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server