drumfire-proxmox-mcp

Удалённый MCP-сервер, который позволяет Claude управлять кластером DRUMFIRE Proxmox через чат — инвентаризация, управление питанием, изменение конфигурации на лету, создание/клонирование ВМ и контейнеров, снапшоты, просмотр сети/фаервола/кластера, выполнение команд внутри гостевой системы и запись файла прямо в файловую систему ВМ через QEMU Guest Agent (здесь используется для обновления калькулятора чистой стоимости, работающего на ВМ 107, свежим экспортом из Firefly III).

Это Cloudflare Worker, разворачиваемый так же, как существующий MCP-сервер Firefly III: нажмите кнопку, задайте несколько секретов, добавьте его в Claude как пользовательский коннектор.

Чего этот сервер намеренно НЕ делает

Здесь нет инструментов удаления ВМ/контейнеров/дисков/снапшотов или отката снапшотов — не «спросить перед действием», а просто отсутствующих в коде, так что они не могут произойти через этот сервер даже по ошибке.

Тем не менее, прочтите примечание по безопасности ниже: поскольку создание ВМ/контейнеров входит в область действия, базовый токен Proxmox технически может удалять их тоже (Proxmox связывает эти разрешения вместе) — здесь гарантия обеспечивается на уровне программного обеспечения (такого инструмента не существует, и Claude проинструктирован всегда спрашивать перед любым деструктивным действием), а не жёсткой стеной на уровне учётных данных, как в v1 этого сервера. См. «Модель безопасности» ниже.

Related MCP server: ProxmoxEmCP

Инструменты, которые предоставляет этот сервер

Модель безопасности

• Инструменты управления питанием/статусом/конфигурацией/созданием/клонированием/созданием снапшотов: считаются «допустимыми» для запуска без предварительного вопроса, согласно тому, как вы это ограничили, — ничего из этого не является деструктивным по своей сути.

• run_guest_command: выполняет всё, что ему сказано, внутри гостевой системы; эквивалент доступа по SSH/RDP. Подходит для диагностики и рутинных изменений; Claude проинструктирован останавливаться и подтверждать с вами перед любым действием, которое выглядит деструктивным или необратимым внутри гостевой системы.

• Ничто в этом сервере не удаляет и не откатывает ВМ, контейнер, диск или снапшот. Это и есть реальная страховка, а не разрешения токена Proxmox — см. роль ниже, которая действительно предоставляет VM.Allocate (требуется для создания, и Proxmox также использует его для удаления — нет способа разделить эти права на уровне разрешений).

1. Создайте ограниченный API-токен Proxmox

Не используйте повторно root/администраторский токен. В веб-интерфейсе Proxmox:

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» установленным и предоставьте самому токену тот же ACL / → ClaudeHomelabOps. Скопируйте ID токена (claude-agent@pve!homelab-mcp) и секрет (показывается один раз) — оба понадобятся вам ниже.

2. Убедитесь, что гостевой агент ВМ калькулятора включён

Инструментам write_vm_file / update_networth_calculator требуется запущенный QEMU Guest Agent внутри ВМ 107 (VM-OnPremTest):

1. На вкладке Options в Proxmox для этой ВМ подтвердите, что «QEMU Guest Agent» включён.

2. Внутри Windows-ВМ установите службу гостевого агента, если её ещё нет (она поставляется на ISO virtio-win как qemu-ga-x86_64.msi) и убедитесь, что служба Windows «QEMU Guest Agent» запущена.

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

Также перепроверьте обычную (не секретную) переменную NETWORTH_VM_PATH в wrangler.jsonc — она поставляется с заполнителем (C:\Users\CHANGE_ME\Documents\net-worth\data.json), в который нужно подставить реальное имя пользователя Windows из шага 2. Измените её в панели 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-ключ, укажите этот заголовок там. Если нет, есть два варианта:

• Вместо этого разместите перед маршрутом Worker политику Cloudflare Access (рекомендуется — это стандартный способ защитить личную MCP-конечную точку, когда клиент не может отправлять собственный заголовок), или

• Как менее безопасный запасной вариант удалите проверку bearer-токена в src/index.ts (fetch(), в начале функции) и полагайтесь на то, что URL самого Worker невозможно угадать. Не рекомендуется для всего, что может получить доступ к Proxmox.

6. Попробуйте

После подключения в чате Claude фразы "перечисли виртуальные машины на drumfire03" или "какой статус у VM 107" должны возвращать реальные данные. Для сценария с расчётом капитала Claude берёт данные из Firefly III (уже подключён), формирует JSON, который ожидает калькулятор, и вызывает update_networth_calculator с этим JSON в виде строки.

Когда это заработает, попробуйте и новые инструменты: "проверь здоровье кластера", "какой у VM 107 актуальный IP прямо сейчас", "клонируй VM-OnPremTest в тестовую копию", "увеличь той VM количество ядер до 4".

Примечание о правах доступа: Точные требования Proxmox к привилегиям для конечных точек управления правилами файрвола и некоторых сетевых операций чтения немного различаются в зависимости от версии, и указанная выше роль — это приблизительное сопоставление, а не проверенное на вашей конкретной версии Proxmox. Если вызов инструмента возвращает 403, сообщение об ошибке содержит фактический ответ Proxmox — решение почти всегда сводится к добавлению ещё одной привилегии роли ClaudeHomelabOps (обычно достаточно лишь подтвердить, что Sys.Audit применяется на /, а не только на вложенном пути).