drumfire-proxmox-mcp

클로드가 채팅으로 DRUMFIRE Proxmox 클러스터를 관리할 수 있게 해주는 원격 MCP 서버 — 인벤토리, 전원 제어, 실시간 구성 변경, VM/컨테이너 생성 및 복제, 스냅샷, 네트워크/방화벽/클러스터 가시성, 게스트 내부에서 명령 실행, 그리고 QEMU Guest Agent를 통해 VM의 파일 시스템에 파일을 직접 푸시(Firefly III의 새 내보내기로 VM 107에서 실행 중인 순자산 계산기를 업데이트하는 데 여기서 사용)까지 처리합니다.

Cloudflare Worker이며, 기존 Firefly III MCP 서버와 같은 방식으로 배포합니다: 버튼을 클릭하고, 몇 가지 시크릿을 설정하고, Claude에 사용자 지정 커넥터로 추가하면 됩니다.

의도적으로 하지 않는 것

VM/컨테이너/디스크/스냅샷 삭제 또는 스냅샷 롤백 도구는 없습니다 — "사전에 묻기"가 아니라 그냥 코드에 존재하지 않으므로, 이 서버를 통해 실수로라도 발생할 수 없습니다.

그렇긴 하지만 아래 보안 노트를 읽어보세요: VM/컨테이너 생성이 범위에 포함되므로 기본 Proxmox 토큰은 기술적으로 이들을 삭제할 수도 있습니다(Proxmox는 이러한 권한을 함께 묶어 둡니다) — 여기서의 보장은 이 서버 v1과 같은 자격 증명 수준의 단단한 벽이 아니라 소프트웨어 수준에서 강제되는 것입니다(그런 도구가 존재하지 않고, Claude는 파괴적인 작업 전에 항상 먼저 묻도록 지시됩니다). 아래 "보안 모델"을 참조하세요.

Related MCP server: proxmox-mcp

이 서버가 노출하는 도구

보안 모델

• 전원/상태/구성/생성/복제/스냅샷 생성 도구: 사용자가 정한 범위에 따라 먼저 묻지 않고 실행해도 "무방한" 것으로 간주합니다 — 여기 있는 어떤 것도 본질적으로 파괴적이지 않습니다.

• run_guest_command: 게스트 내부에서 지시된 모든 것을 실행하며, SSH/RDP 액세스에 해당합니다. 진단 및 일상적인 변경에는 적합합니다. Claude는 게스트 내부에서 파괴적이거나 되돌릴 수 없어 보이는 작업 전에 멈추고 사용자에게 확인하도록 지시됩니다.

• 이 서버의 어떤 것도 VM, 컨테이너, 디스크 또는 스냅샷을 삭제하거나 롤백하지 않습니다. 이것이 실제 최후의 방어선이며, Proxmox 토큰의 권한이 아닙니다 — 아래 역할에서 알 수 있듯이 VM.Allocate를 부여합니다(생성에 필요하며, Proxmox는 삭제에도 이 권한을 사용합니다 — 권한 수준에서 이를 분리할 방법은 없습니다).

1. 범위가 제한된 Proxmox API 토큰 만들기

루트/관리자 토큰을 재사용하지 마세요. Proxmox 웹 UI에서:

1. Datacenter → Permissions → Roles → Create 이름: ClaudeHomelabOps. 권한: VM.Audit, VM.Monitor, VM.PowerMgmt, Sys.Audit, VM.Allocate, VM.Clone, VM.Snapshot, VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.Options, VM.Config.HWType, VM.Config.CDROM, VM.Config.Cloudinit.

   의도적으로 VM.Snapshot.Rollback(롤백은 현재 디스크 상태를 폐기하므로 — 진정으로 파괴적임)과 VM.Backup/VM.Migrate/VM.Console(이 서버가 하는 어떤 일에도 필요하지 않음)을 제외합니다. 위에서 설명했듯이 VM.Allocate는 create_vm/create_container/clone_vm에 필요하며 Proxmox는 게스트 삭제에도 이를 사용합니다 — 더 세분화된 분리 방법이 없으므로 여기서의 "삭제 불가" 보장은 이 서버에 삭제 도구가 단순히 없다는 데서 오는 것이지 토큰 권한에서 오는 것이 아닙니다.

   일상적으로 더 강한 자격 증명 수준의 보장을 유지하고 생성 권한만 일시적으로 부여하려면, 두 번째로 더 제한된 토큰(이 동일한 역할에서 VM.Allocate/VM.Config.*를 뺀 것)을 대신 만들고 실제로 무언가를 생성/재구성할 때 이 Worker가 사용하는 시크릿을 전환하면 됩니다 — 앞서 절충안 질문은 단순함을 위해 토큰 하나를 기본값으로 했지만, 여기서 그렇게 해야 한다는 요구는 없습니다.

2. Datacenter → Permissions → Users → Add에서 전용 사용자(예: claude-agent@pve)를 추가하세요. (비밀번호는 필요 없으며, API 토큰으로만 인증됩니다.)

3. Datacenter → Permissions → Add → 경로 /, 사용자 claude-agent@pve, 역할 ClaudeHomelabOps.

4. Datacenter → Permissions → API Tokens → Add → 사용자 claude-agent@pve, 토큰 ID 예: homelab-mcp. "Privilege Separation"은 체크된 상태로 두고 토큰 자체에도 동일한 / → ClaudeHomelabOps ACL을 부여하세요. Token ID(claude-agent@pve!homelab-mcp)와 시크릿(한 번만 표시됨)을 복사해 두세요 — 아래에서 둘 다 필요합니다.

2. 계산기 VM의 게스트 에이전트가 활성화되어 있는지 확인

write_vm_file / update_networth_calculator 도구는 VM 107(VM-OnPremTest) 내부에서 QEMU Guest Agent가 실행 중이어야 합니다:

1. Proxmox의 VM Options 탭에서 "QEMU Guest Agent"가 활성화되어 있는지 확인하세요.

2. Windows VM 내부에 게스트 에이전트 서비스가 아직 없다면 설치하세요 (virtio-win ISO에 qemu-ga-x86_64.msi로 포함되어 있습니다). 그리고 "QEMU Guest Agent" Windows 서비스가 실행 중인지 확인하세요.

3. 앱의 데이터 폴더가 어떤 Windows 사용자 계정 아래에 있는지 확인해 두세요 — 게스트 에이전트 서비스는 SYSTEM으로 실행되므로 파일 쓰기에는 전체 절대 경로가 필요합니다(예: C:\Users\<username>\Documents\net-worth\data.json). 상대 경로로는 안 됩니다.

3. 배포

(먼저 이 저장소를 GitHub에 푸시한 다음, 위의 REPLACE_WITH_THIS_REPO_URL을 https://github.com/<you>/<repo>로 바꾸세요 — GitHub는 저장소가 존재하기 전에는 버튼이 자기 자신을 가리키도록 허용하지 않습니다.)

버튼을 클릭하면 저장소를 Cloudflare Workers Builds에 포크/연결하고 배포를 대신 실행합니다. 다만 아직 사용할 수는 없습니다 — 4단계를 참조하세요.

수동 배포(버튼 대신)

npm install
npx wrangler secret put PROXMOX_TOKEN_ID
npx wrangler secret put PROXMOX_TOKEN_SECRET
npx wrangler secret put MCP_BEARER_TOKEN   # any long random string you generate
npx wrangler deploy

4. 배포 후 시크릿 설정하기

버튼을 사용했든 CLI를 사용했든 세 가지 시크릿이 필요하며, 의도적으로 이 저장소에는 없습니다 (wrangler.jsonc에도 들어 있지 않으며, 이 파일은 공개되어도 무방합니다):

Cloudflare 대시보드에서 Worker → Settings → Variables and Secrets → Add → Encrypt에서 설정하거나 npx wrangler secret put <NAME>으로 설정하세요.

또한 wrangler.jsonc의 일반(비시크릿) 변수 NETWORTH_VM_PATH도 다시 확인하세요 — 2단계의 실제 Windows 사용자 이름이 필요한 플레이스홀더(C:\Users\CHANGE_ME\Documents\net-worth\data.json)가 포함된 채로 제공됩니다. Cloudflare 대시보드의 동일한 Variables and Secrets 페이지에서 (시크릿이 아닌 일반 텍스트 변수로) 편집하거나, wrangler.jsonc를 편집한 후 재배포하세요.

5. Claude에 사용자 지정 커넥터로 추가하기

Claude의 커넥터 설정에서 다음을 가리키는 사용자 지정 커넥터를 추가하세요:

https://<your-worker-subdomain>.workers.dev/mcp

이 Worker는 어떤 작업을 하기 전에 모든 요청에 Authorization: Bearer <MCP_BEARER_TOKEN>이 포함되어 있는지 확인합니다 — 이 토큰이 없으면 모든 도구 호출은 401을 받습니다. Claude 커넥터 설정에서 사용자 지정 헤더/API 키를 첨부할 수 있다면 해당 헤더를 거기에 설정하세요. 그럴 수 없다면 두 가지 옵션이 있습니다:

• Cloudflare Access 정책을 Worker 라우트 앞에 배치하세요(권장 — 클라이언트가 사용자 지정 헤더를 보낼 수 없을 때 개인 MCP 엔드포인트를 잠그는 표준 방식), 또는

• 보안 수준이 낮은 대체 방법으로, src/index.ts에 있는 Bearer 토큰 검사(fetch(), 함수 상단)를 삭제하고 Worker의 URL 자체가 추측 불가능한 점에 의존하세요. Proxmox에 접근할 수 있는 용도에는 권장되지 않습니다.

6. 시도해 보기

연결이 완료되면 Claude 채팅에서 "drumfire03의 VM 목록을 보여줘" 또는 *"VM 107의 상태가 뭐야?"*라고 하면 실제 데이터가 반환됩니다. 순자산 워크플로의 경우, Claude는 Firefly III(이미 연결됨)에서 데이터를 가져오고, 계산기가 기대하는 JSON을 만든 다음, 해당 JSON을 문자열로 전달하면서 update_networth_calculator를 호출합니다.

이것이 작동하면 새로운 도구들도 시도해 보세요 — "클러스터 상태 확인해 줘", "VM 107의 실제 IP가 지금 뭐야?", "VM-OnPremTest를 테스트 복사본으로 복제해 줘", "그 VM을 4코어로 올려 줘".

권한 관련 참고: Proxmox의 정확한 권한 요구 사항은 방화벽 규칙 및 일부 네트워크 읽기 엔드포인트에 대해 버전에 따라 다소 다르며, 위의 역할은 최선의 매핑일 뿐 특정 Proxmox 버전에 대해 테스트된 것이 아닙니다. 도구 호출이 403으로 돌아오면 오류 메시지에 Proxmox의 실제 응답이 포함됩니다. 해결 방법은 거의 항상 ClaudeHomelabOps에 권한 하나를 더 추가하는 것입니다(일반적으로 Sys.Audit이 하위 경로가 아닌 /에 적용되어 있는지 다시 확인하는 것).