Skip to main content
Glama
enesjakozh
canvrno

Proxmox MCP Server

by canvrno
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

🚀 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. 복제하고 환경을 설정합니다.

    지엑스피1

  2. 종속성 설치:

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

  3. 구성 생성:

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

  4. 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 } }

설치 확인

  1. Python 환경 확인:

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

  2. 테스트를 실행하세요:

    pytest

  3. 구성 확인:

    # 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 토큰 설정

  1. Proxmox 웹 인터페이스에 로그인하세요

  2. 데이터 센터 -> 권한 -> API 토큰으로 이동합니다.

  3. 새로운 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 라이센스

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

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/canvrno/ProxmoxMCP'

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