drumfire-proxmox-mcp

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

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

의도적으로 하지 않는 일

VM/컨테이너/디스크/스냅샷 삭제 도구나 스냅샷 롤백 도구는 없습니다. "사전 확인"이 아니라 그냥 코드에 존재하지 않으므로, 이 서버를 통해서는 실수로라도 그런 작업이 일어날 수 없습니다.

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

Related MCP server: ProxmoxEmCP

이 서버가 제공하는 도구

보안 모델

• 전원/상태/구성/생성/복제/스냅샷 생성 도구: 여러분이 범위를 정한 방식에 따라 사전 확인 없이 실행해도 되는 "정당한 작업"으로 취급됩니다. 여기에는 본질적으로 파괴적인 것이 없습니다.

• run_guest_command: 지시받은 내용을 게스트 내부에서 실행하며, SSH/RDP 액세스와 동등합니다. 진단 및 일상적 변경에는 적합합니다. Claude는 게스트 내부에서 파괴적이거나 되돌릴 수 없어 보이는 작업을 하기 전에 멈추고 여러분에게 확인하도록 지시받습니다.

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

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

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

1. 데이터센터 → 권한 → 역할 → 만들기 이름: 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. 데이터센터 → 권한 → 사용자 → 추가 전용 사용자(예: claude-agent@pve)를 추가합니다. (비밀번호는 필요 없습니다. API 토큰으로만 인증합니다.)

3. 데이터센터 → 권한 → 추가 → 경로 /, 사용자 claude-agent@pve, 역할 ClaudeHomelabOps.

4. 데이터센터 → 권한 → API 토큰 → 추가 → 사용자 claude-agent@pve, 토큰 ID (예: homelab-mcp). "권한 분리"를 체크된 상태로 두고 토큰 자체에도 동일한 / → 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 옵션 탭에서 "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 → 설정 → 변수 및 시크릿 → 추가 → 암호화에서 설정하거나, npx wrangler secret put <NAME>으로 설정합니다.

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

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

Claude의 커넥터 설정에서 다음을 가리키는 사용자 지정 커넥터를 추가합니다.

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

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

• Worker의 라우트 앞에 Cloudflare Access 정책을 두십시오(권장 — 클라이언트가 사용자 지정 헤더를 보낼 수 없을 때 개인 MCP 엔드포인트를 잠그는 표준적인 방법입니다), 또는

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

6. 사용해 보기

연결되면 Claude 채팅에서 "drumfire03에 있는 VM 목록을 보여 줘" 또는 *"VM 107의 상태가 뭐야"*라고 입력하면 실제 데이터가 반환되어야 합니다. net worth 워크플로의 경우, Claude는 Firefly III(이미 연결됨)에서 데이터를 가져와 계산기가 기대하는 JSON을 구성하고, 해당 JSON을 문자열로 update_networth_calculator를 호출합니다.

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

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