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: proxmox-mcp

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

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

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

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

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

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

Не переиспользуйте root/admin токен. В веб-интерфейсе 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 также использует его для удаления гостевой системы — более гранулярного разделения нет, поэтому гарантия «нельзя удалить» здесь обеспечивается тем, что у этого сервера просто нет инструмента удаления, а не разрешениями токена.

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-ключ, задайте этот заголовок там. Если нет, есть два варианта:

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

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

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

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

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

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