🚀 Proxmox Manager - Proxmox MCP 서버

프록스목스MCP

Proxmox 하이퍼바이저와 상호 작용하기 위한 Python 기반 MCP(Model Context Protocol) 서버로, 노드, VM 및 컨테이너를 관리하기 위한 깔끔한 인터페이스를 제공합니다.

🏗️ ~로 구축됨

클라인 - 자율 코딩 에이전트 - 클라인으로 더 빠르게 작업하세요.
Proxmoxer - Proxmox API를 위한 Python 래퍼
MCP SDK - 모델 컨텍스트 프로토콜 SDK
Pydantic - Python 유형 주석을 사용한 데이터 검증

Related MCP server: MCP Builder

✨ 특징

🤖 Cline과 완벽하게 통합됨
🛠️ 공식 MCP SDK로 구축됨
🔒 Proxmox를 사용한 안전한 토큰 기반 인증
🖥️ 노드 및 VM 관리 도구
💻 VM 콘솔 명령 실행
📝 구성 가능한 로깅 시스템
✅ Pydantic을 사용한 유형 안전 구현
🎨 사용자 정의 가능한 테마를 사용한 풍부한 출력 형식

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 설치

필수 조건

UV 패키지 관리자(권장)
Python 3.10 이상
깃
API 토큰 자격 증명을 사용하여 Proxmox 서버에 액세스

시작하기 전에 다음 사항을 확인하세요.

[ ] Proxmox 서버 호스트 이름 또는 IP
[ ] Proxmox API 토큰( API 토큰 설정 참조)
[ ] UV 설치됨 ( pip install uv )

옵션 1: 빠른 설치(권장)

복제하고 환경을 설정합니다.
지엑스피1

종속성 설치:

# Install with development dependencies
uv pip install -e ".[dev]"

구성 생성:

# Create config directory and copy template
mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json

proxmox-config/config.json 편집합니다:

{
    "proxmox": {
        "host": "PROXMOX_HOST",        # Required: Your Proxmox server address
        "port": 8006,                  # Optional: Default is 8006
        "verify_ssl": false,           # Optional: Set false for self-signed certs
        "service": "PVE"               # Optional: Default is PVE
    },
    "auth": {
        "user": "USER@pve",            # Required: Your Proxmox username
        "token_name": "TOKEN_NAME",    # Required: API token ID
        "token_value": "TOKEN_VALUE"   # Required: API token value
    },
    "logging": {
        "level": "INFO",               # Optional: DEBUG for more detail
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"      # Optional: Log to file
    }
}

설치 확인

Python 환경 확인:

python -c "import proxmox_mcp; print('Installation OK')"

테스트를 실행하세요:
```
pytest
```

구성 확인:

# Linux/macOS
PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server

# Windows (PowerShell)
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

다음 중 하나가 표시되어야 합니다.

Proxmox 서버에 성공적으로 연결되었습니다.
또는 연결 오류(Proxmox 세부 정보가 올바르지 않은 경우)

⚙️ 구성

Proxmox API 토큰 설정

Proxmox 웹 인터페이스에 로그인하세요
데이터 센터 -> 권한 -> API 토큰으로 이동합니다.
새로운 API 토큰을 만듭니다.
- 사용자를 선택하세요(예: root@pam)
- 토큰 ID를 입력하세요(예: "mcp-token")
- 전체 액세스를 원하시면 "권한 분리"를 선택 해제하세요.
- 토큰 ID와 비밀번호를 모두 저장하고 복사하세요.

🚀 서버 실행

개발 모드

테스트 및 개발을 위해:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

클라인 데스크톱 통합

Cline 사용자의 경우 이 구성을 MCP 설정 파일(일반적으로 ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json )에 추가하세요.

{
    "mcpServers": {
        "github.com/canvrno/ProxmoxMCP": {
            "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

올바른 경로를 생성하려면 다음 명령을 사용할 수 있습니다.

# This will print the MCP settings with your absolute paths filled in
python -c "import os; print(f'''{{
    \"mcpServers\": {{
        \"github.com/canvrno/ProxmoxMCP\": {{
            \"command\": \"{os.path.abspath('.venv/bin/python')}\",
            \"args\": [\"-m\", \"proxmox_mcp.server\"],
            \"cwd\": \"{os.getcwd()}\",
            \"env\": {{
                \"PYTHONPATH\": \"{os.path.abspath('src')}\",
                \"PROXMOX_MCP_CONFIG\": \"{os.path.abspath('proxmox-config/config.json')}\",
                ...
            }}
        }}
    }}
}}''')"

중요한:

모든 경로는 절대적이어야 합니다.
Python 인터프리터는 가상 환경에서 나와야 합니다.
PYTHONPATH는 src 디렉토리를 가리켜야 합니다.
MCP 설정을 업데이트한 후 VSCode를 다시 시작하세요.

🔧 사용 가능한 도구

서버는 Proxmox와 상호 작용하기 위한 다음과 같은 MCP 도구를 제공합니다.

노드를 얻으세요

Proxmox 클러스터의 모든 노드를 나열합니다.

매개변수: 없음

응답 예시:

🖥️ Proxmox Nodes

🖥️ pve-compute-01
  • Status: ONLINE
  • Uptime: ⏳ 156d 12h
  • CPU Cores: 64
  • Memory: 186.5 GB / 512.0 GB (36.4%)

🖥️ pve-compute-02
  • Status: ONLINE
  • Uptime: ⏳ 156d 11h
  • CPU Cores: 64
  • Memory: 201.3 GB / 512.0 GB (39.3%)

노드 상태 가져오기

특정 노드의 자세한 상태를 가져옵니다.

매개변수:
- node (문자열, 필수): 노드의 이름

응답 예시:

🖥️ Node: pve-compute-01
  • Status: ONLINE
  • Uptime: ⏳ 156d 12h
  • CPU Usage: 42.3%
  • CPU Cores: 64 (AMD EPYC 7763)
  • Memory: 186.5 GB / 512.0 GB (36.4%)
  • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
  • Temperature: 38°C

get_vms

클러스터 전체의 모든 VM을 나열합니다.

매개변수: 없음

응답 예시:

🗃️ Virtual Machines

🗃️ prod-db-master (ID: 100)
  • Status: RUNNING
  • Node: pve-compute-01
  • CPU Cores: 16
  • Memory: 92.3 GB / 128.0 GB (72.1%)

🗃️ prod-web-01 (ID: 102)
  • Status: RUNNING
  • Node: pve-compute-01
  • CPU Cores: 8
  • Memory: 12.8 GB / 32.0 GB (40.0%)

저장소 가져오기

사용 가능한 저장 공간을 나열하세요.

매개변수: 없음

응답 예시:

💾 Storage Pools

💾 ceph-prod
  • Status: ONLINE
  • Type: rbd
  • Usage: 12.8 TB / 20.0 TB (64.0%)
  • IOPS: ⬆️ 15.2k ⬇️ 12.8k

💾 local-zfs
  • Status: ONLINE
  • Type: zfspool
  • Usage: 3.2 TB / 8.0 TB (40.0%)
  • IOPS: ⬆️ 42.8k ⬇️ 35.6k

클러스터 상태 가져오기

전반적인 클러스터 상태를 가져옵니다.

매개변수: 없음

응답 예시:

⚙️ Proxmox Cluster

  • Name: enterprise-cloud
  • Status: HEALTHY
  • Quorum: OK
  • Nodes: 4 ONLINE
  • Version: 8.1.3
  • HA Status: ACTIVE
  • Resources:
    - Total CPU Cores: 192
    - Total Memory: 1536 GB
    - Total Storage: 70 TB
  • Workload:
    - Running VMs: 7
    - Total VMs: 8
    - Average CPU Usage: 38.6%
    - Average Memory Usage: 42.8%

실행_vm_명령

QEMU Guest Agent를 사용하여 VM 콘솔에서 명령을 실행합니다.

매개변수:
- node (문자열, 필수): VM이 실행 중인 노드의 이름
- vmid (문자열, 필수): VM의 ID
- command (문자열, 필수): 실행할 명령

응답 예시:

🔧 Console Command Result
  • Status: SUCCESS
  • Command: systemctl status nginx
  • Node: pve-compute-01
  • VM: prod-web-01 (ID: 102)

Output:
● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago

요구 사항:
- VM이 실행 중이어야 합니다.
- QEMU 게스트 에이전트는 VM에 설치되어 실행되어야 합니다.
- 게스트 에이전트에서 명령 실행 권한을 활성화해야 합니다.
오류 처리:
- VM이 실행 중이 아니면 오류가 반환됩니다.
- VM을 찾을 수 없으면 오류가 반환됩니다.
- 명령 실행이 실패하면 오류를 반환합니다.
- 명령이 0이 아닌 종료 코드를 반환하더라도 명령 출력을 포함합니다.

👨‍💻 개발

가상 환경을 활성화한 후:

테스트 실행: pytest
포맷 코드: black .
유형 검사: mypy .
린트: ruff .

📁 프로젝트 구조

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # Main MCP server implementation
│       ├── config/            # Configuration handling
│       ├── core/              # Core functionality
│       ├── formatting/        # Output formatting and themes
│       ├── tools/             # Tool implementations
│       │   └── console/       # VM console operations
│       └── utils/             # Utilities (auth, logging)
├── tests/                     # Test suite
├── proxmox-config/
│   └── config.example.json    # Configuration template
├── pyproject.toml            # Project metadata and dependencies
└── LICENSE                   # MIT License

📄 라이센스

MIT 라이센스

Proxmox MCP Server

🚀 Proxmox Manager - Proxmox MCP 서버

🏗️ ~로 구축됨

✨ 특징

📦 설치

필수 조건

옵션 1: 빠른 설치(권장)

설치 확인

⚙️ 구성

Proxmox API 토큰 설정

🚀 서버 실행

개발 모드

클라인 데스크톱 통합

🔧 사용 가능한 도구

노드를 얻으세요

노드 상태 가져오기

get_vms

저장소 가져오기

클러스터 상태 가져오기

실행_vm_명령

👨‍💻 개발

📁 프로젝트 구조

📄 라이센스

Resources

Appeared in Searches

Latest Blog Posts

MCP directory API