talos-mcp

Release Go Reference codecov Go Report Card OpenSSF Scorecard License

MCP-сервер, который предоставляет AI-агентам (Claude Code, OpenAI Codex и любым MCP-совместимым клиентам) возможности управления кластером Talos Linux. Вместо того чтобы копировать вывод talosctl в чат, агент вызывает структурированные инструменты, которые возвращают машиночитаемый JSON напрямую из gRPC API Talos — нулевые затраты токенов на промежуточный вывод.

Подключается к вашему кластеру через нативный gRPC API Talos, используя те же учетные данные mTLS, что и talosctl (~/.talos/config).

Установка

Через npm (Go не требуется, Linux/macOS, amd64/arm64):

npx talos-mcp

Скачать бинарный файл (Linux/macOS, amd64/arm64):

Скачайте последний релиз с GitHub Releases, распакуйте и поместите бинарный файл в ваш $PATH.

Сборка из исходного кода (требуется Go 1.21+):

git clone https://github.com/Nosmoht/talos-mcp-server
cd talos-mcp
go build -o talos-mcp .

Конфигурация

По умолчанию считывает ~/.talos/config (тот же файл, который использует talosctl). Переопределяется через переменные окружения:

Переменная	По умолчанию	Описание
`TALOSCONFIG`	`~/.talos/config`	Путь к файлу talosconfig
`TALOS_CONTEXT`	активный контекст	Имя используемого контекста
`TALOS_ENDPOINTS`	из конфига	Переопределение эндпоинтов через запятую
`TALOS_MCP_READ_ONLY`	`false`	Установите `true` для отключения всех изменяющих инструментов при запуске
`TALOS_MCP_ALLOWED_PATHS`	(все)	Префиксы путей через запятую, разрешенные для `talos_read_file` и `talos_list_files` (например, `/etc,/proc`)
`TALOS_MCP_SKIP_VERSION_CHECK`	`false`	Установите `true` для пропуска проверки пути обновления (например, для заводских образов или пользовательских тегов)

Совместимость

Этот сервер протестирован с Talos Linux версий от v1.9.x до v1.12.x.

talos-mcp	Talos Linux	machinery SDK
v0.x (текущая)	v1.9.0 – v1.12.x	v1.12.6

Сервер записывает предупреждение при запуске, если версия Talos подключенного кластера выходит за пределы протестированного диапазона. Все 19 используемых методов gRPC остаются стабильными начиная с Talos v1.9.

Проверка пути обновления

Инструмент talos_upgrade проверяет, соответствует ли целевая версия поддерживаемому пути обновления Talos — не более одной минорной версии за раз (например, v1.11.x → v1.12.x). Обновления, пропускающие минорные версии, отклоняются с ошибкой.

Если ваш образ использует пользовательский или заводской тег (например, factory.talos.dev/... или :latest), тег не может быть проанализирован, и проверка автоматически пропускается. Чтобы явно пропустить проверку, установите TALOS_MCP_SKIP_VERSION_CHECK=true.

Настройка клиента

Claude Code

Добавьте в .mcp.json вашего проекта:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

Или глобально в ~/.claude.json в разделе "mcpServers". Если вы предпочитаете локальный бинарный файл, замените "command": "npx" на путь к файлу.

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

OpenAI Codex

Добавьте в .codex/config.toml (проект) или ~/.codex/config.toml (глобально):

[mcp_servers.talos]
command = "npx"
args = ["-y", "talos-mcp"]

[mcp_servers.talos.env]
TALOSCONFIG = "/path/to/talosconfig"

Универсальный MCP-клиент

Сервер использует протокол MCP через stdio:

./talos-mcp

Инструменты

Только для чтения

Инструмент	Описание
`talos_resource_definitions`	Список всех доступных типов ресурсов и их псевдонимов. Вызывайте первым, чтобы узнать, что можно запрашивать.
`talos_get`	Получение или список любого ресурса COSI по типу (например, `MachineStatus`, `Member`, `NodeAddress`, `Service`).
`talos_version`	Получение информации о версии Talos с целевых узлов.
`talos_services`	Список всех служб Talos и их текущего состояния (запущена, остановлена, работоспособность).
`talos_containers`	Список контейнеров в пространстве имен (по умолчанию: `k8s.io` для контейнеров Kubernetes).
`talos_processes`	Список запущенных процессов на целевых узлах.
`talos_health`	Проверка работоспособности кластера (etcd, Kubernetes API, готовность узлов). Поддерживает переопределение `control_plane_nodes` / `worker_nodes`.
`talos_logs`	Получение последних логов службы (последние N строк, без слежения).
`talos_dmesg`	Чтение сообщений кольцевого буфера ядра.
`talos_events`	Получение последних событий среды выполнения Talos (изменения служб, изменения конфигурации).
`talos_etcd`	Запрос к кластеру etcd: `members` (по умолчанию) или `status`.
`talos_list_files`	Список файлов и директорий в файловой системе узла.
`talos_read_file`	Чтение содержимого файла из файловой системы узла.

Изменяющие состояние

Эти инструменты изменяют состояние кластера и имеют явные механизмы защиты.

Инструмент	Описание	Защита
`talos_service_action`	Запуск, остановка или перезапуск службы Talos (примечание: перезапуск `etcd` не поддерживается API Talos).	—
`talos_reboot`	Перезагрузка целевых узлов. Поддерживает `mode`: `default`, `powercycle`, `force`.	требуется `confirm=true`; `nodes` должны быть указаны явно
`talos_upgrade`	Обновление Talos на целевых узлах. Поддерживает `preserve` (по умолчанию `true`), `stage`, `force`, `reboot_mode`.	требуется `confirm=true`; `nodes` и `image` обязательны
`talos_rollback`	Откат последнего обновления на целевых узлах.	требуется `confirm=true`; `nodes` должны быть указаны явно
`talos_patch_config`	Применение патча конфигурации машины (JSON или YAML strategic merge).	`dry_run` по умолчанию `true`; требуется `confirm=true`, если `dry_run=false`

Все инструменты принимают необязательное поле nodes (список IP-адресов или имен хостов узлов). Если оно опущено, используется активный контекст из talosconfig.

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

Границы доверия

MCP Client (Claude Code / Codex)
        │  stdio / JSON-RPC
        ▼
   talos-mcp  ◄── reads TALOSCONFIG (~/.talos/config)
        │  gRPC + mTLS
        ▼
  Talos API (each node)
        │
        ▼
    Node OS

Предупреждение о потоке данных: Ответы инструментов попадают непосредственно в контекстное окно LLM и отправляются провайдеру LLM. Все, что возвращает инструмент — IP-адреса узлов, имена хостов, конфигурации служб, логи ядра, содержимое файлов — становится частью промпта, отправляемого по сети. Не используйте этот сервер с кластерами, содержащими данные, которые вы не хотели бы отправлять провайдеру LLM.

RBAC Talos принудительно применяется на стороне сервера. Учетные данные в вашем talosconfig определяют, какие операции разрешены на каждом узле. talos-mcp не может обойти RBAC Talos — запрос, который отклоняет API, завершится ошибкой, а не выполнится молча.

Классификация инструментов и минимально необходимая роль RBAC

Инструмент	Минимальный RBAC
`talos_resource_definitions`, `talos_get`, `talos_version`, `talos_services`, `talos_containers`, `talos_processes`, `talos_health`, `talos_logs`, `talos_dmesg`, `talos_events`, `talos_list_files`, `talos_read_file`	`os:reader`
`talos_etcd`, `talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`	`os:operator`
`talos_patch_config`	`os:admin`

Механизмы безопасности

Механизм	Как это работает
Режим только для чтения	`TALOS_MCP_READ_ONLY=true` регистрирует только инструменты для чтения при запуске; изменяющие инструменты никогда не предоставляются LLM
Белый список путей	`TALOS_MCP_ALLOWED_PATHS=/etc,/proc` ограничивает `talos_read_file` и `talos_list_files` указанными префиксами
Подтверждение действий	`talos_reboot`, `talos_upgrade`, `talos_rollback` и `talos_patch_config` (когда `dry_run=false`) требуют `confirm=true`; принудительно на стороне сервера
Сохранение по умолчанию	`talos_upgrade` по умолчанию устанавливает `preserve` в `true` (сохранение раздела EPHEMERAL) — отличается от значения `false` по умолчанию в `talosctl`
Dry-run по умолчанию	`talos_patch_config` по умолчанию имеет `dry_run=true`; для применения требуется и `dry_run=false`, и `confirm=true`
Аудит логирования	Все вызовы изменяющих инструментов (`talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`, `talos_patch_config`) выводят структурированную строку лога в stderr: `AUDIT timestamp=<RFC3339> tool=<name> nodes=<list> args=<json>` (содержимое патча скрыто)

Что не входит в модель угроз

Сама LLM — промпт-инъекции, галлюцинации аргументов инструментов и хранение данных провайдером LLM находятся вне области ответственности этого сервера
MCP-клиент — безопасность Claude Code, Codex или других MCP-клиентов является ответственностью этих проектов
Сетевой путь между talos-mcp и узлами Talos — защищен взаимным TLS с использованием учетных данных из вашего talosconfig

Настройка учетных данных с минимальными привилегиями

Создайте выделенный talosconfig с минимальными разрешениями для использования с этим сервером:

Доступ только для чтения (рекомендуется для большинства случаев):

# Generate a reader-only talosconfig
talosctl config new --roles=os:reader talosconfig-readonly

Затем установите TALOSCONFIG=/path/to/talosconfig-readonly и TALOS_MCP_READ_ONLY=true для максимального ограничения. При такой настройке сервер предоставляет только инструменты для чтения, и учетные данные не могут выполнять никаких изменяющих операций, даже если инструмент будет каким-то образом обойден.

Доступ оператора (для управления службами, перезагрузки, обновления):

talosctl config new --roles=os:operator talosconfig-operator

Это охватывает все инструменты, кроме talos_patch_config (который требует os:admin).

Полный доступ (требуется для патчинга конфигурации):

Используйте ваш стандартный talosconfig или создайте новый с os:admin. Оставьте это для настроек, где явно требуется возможность патчинга конфигурации.

Проверка загрузок

Контрольные суммы (целостность)

Каждый релиз включает файл talos-mcp_<version>_checksums.txt с хешами SHA-256 всех архивов. Проверьте бинарный файл после скачивания:

# Download archive and checksums
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_linux_amd64.tar.gz
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_checksums.txt

# Verify
sha256sum --check --ignore-missing talos-mcp_<version>_checksums.txt

Это обнаруживает повреждение или неполную загрузку. Это не защищает от скомпрометированного конвейера выпуска.

Аттестации артефактов GitHub (происхождение SLSA L2)

Каждый релиз включает аттестацию происхождения сборки, встроенную в GitHub, которая криптографически связывает бинарный файл с конкретным коммитом и запуском рабочего процесса, который его создал:

gh attestation verify talos-mcp_<version>_linux_amd64.tar.gz \
  --repo Nosmoht/talos-mcp-server

Это требует GitHub CLI. Успешная проверка означает, что артефакт был создан официальным рабочим процессом выпуска в этом репозитории, а не сторонней сборкой.

Происхождение пакета npm

Пакет npm публикуется с аттестацией происхождения:

npm audit signatures

Успешный результат означает, что пакет был опубликован официальным рабочим процессом выпуска GitHub Actions через доверенную публикацию OIDC.

Разработка

# Build
go build -o talos-mcp .

# Test
go test -race ./...

# Lint (requires golangci-lint v2)
golangci-lint run

# Format check
gofmt -l .

Лицензия

MIT

Talos Linux MCP Server