talos-mcp

Un servidor MCP que expone la gestión de clústeres de Talos Linux a agentes de IA (Claude Code, OpenAI Codex y cualquier cliente compatible con MCP). En lugar de pegar la salida de talosctl en el chat, el agente llama a herramientas estructuradas que devuelven JSON legible por máquina directamente desde la API gRPC de Talos, con coste cero de tokens por salida intermedia.

Se conecta a tu clúster a través de la API gRPC nativa de Talos utilizando las mismas credenciales mTLS que talosctl (~/.talos/config).

Instalación

Vía npm (no requiere Go, Linux/macOS, amd64/arm64):

npx talos-mcp

Descargar binario (Linux/macOS, amd64/arm64):

Descarga la última versión desde GitHub Releases, descomprime y coloca el binario en tu $PATH.

Compilar desde el código fuente (requiere Go 1.21+):

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

Configuración

Lee ~/.talos/config por defecto (el mismo archivo que usa talosctl). Se puede sobrescribir mediante variables de entorno:

Compatibilidad

Este servidor ha sido probado con Talos Linux desde la v1.9.x hasta la v1.12.x.

El servidor registra una advertencia de inicio si la versión de Talos del clúster conectado está fuera del rango probado. Los 19 métodos gRPC utilizados han sido estables desde Talos v1.9.

Validación de la ruta de actualización

La herramienta talos_upgrade valida que la versión de destino siga la ruta de actualización admitida por Talos: como máximo una versión menor a la vez (ej. v1.11.x → v1.12.x). Las actualizaciones que omiten versiones menores se rechazan con un error.

Si tu imagen utiliza una etiqueta personalizada o de fábrica (ej. factory.talos.dev/... o :latest), la etiqueta no se puede analizar y la validación se omite automáticamente. Para omitir la validación explícitamente, establece TALOS_MCP_SKIP_VERSION_CHECK=true.

Configuración del cliente

Claude Code

Añádelo al archivo .mcp.json de tu proyecto:

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

O globalmente en ~/.claude.json bajo "mcpServers". Si prefieres un binario local, reemplaza "command": "npx" con la ruta al binario.

Claude Desktop

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json:

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

OpenAI Codex

Añádelo a .codex/config.toml (proyecto) o ~/.codex/config.toml (global):

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

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

Cliente MCP genérico

El servidor habla el protocolo MCP a través de stdio:

./talos-mcp

Herramientas

Solo lectura

Mutación

Estas herramientas modifican el estado del clúster y tienen protecciones de seguridad explícitas.

Todas las herramientas aceptan un campo opcional nodes (lista de IPs o nombres de host de los nodos). Cuando se omite, se utiliza el contexto activo de talosconfig.

Modelo de seguridad

Límites de confianza

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

Advertencia de flujo de datos: Las respuestas de las herramientas fluyen directamente a la ventana de contexto del LLM y se envían al proveedor del LLM. Todo lo que devuelve una herramienta (IPs de nodos, nombres de host, configuraciones de servicio, registros del kernel, contenido de archivos) se convierte en parte del prompt enviado a través de la red. No utilices este servidor con clústeres que contengan datos que no te sentirías cómodo enviando a tu proveedor de LLM.

El RBAC de Talos se aplica en el lado del servidor. Las credenciales en tu talosconfig determinan qué operaciones están permitidas en cada nodo. talos-mcp no puede omitir el RBAC de Talos: una solicitud que la API rechaza fallará con un error, no tendrá éxito silenciosamente.

Clasificación de herramientas y rol RBAC mínimo requerido

Mecanismos de seguridad

Lo que no está en el modelo de amenazas

• El LLM en sí — la inyección de prompts, los argumentos de herramientas alucinados y la retención de datos del proveedor de LLM están fuera del alcance de este servidor

• El cliente MCP — la seguridad de Claude Code, Codex u otros clientes MCP es responsabilidad de esos proyectos

• Ruta de red entre talos-mcp y los nodos de Talos — protegida por TLS mutuo utilizando las credenciales en tu talosconfig

Configuración de credenciales de menor privilegio

Crea un talosconfig dedicado con permisos mínimos para usar con este servidor:

Acceso de solo lectura (recomendado para la mayoría de los casos de uso):

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

Luego establece TALOSCONFIG=/ruta/a/talosconfig-readonly y TALOS_MCP_READ_ONLY=true para una restricción máxima. Con esta configuración, el servidor expone solo herramientas de solo lectura y las credenciales no pueden realizar ninguna operación de mutación, incluso si una herramienta fuera omitida de alguna manera.

Acceso de operador (para gestión de servicios, reinicio, actualización):

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

Esto cubre todas las herramientas excepto talos_patch_config (que requiere os:admin).

Acceso completo (requerido para parches de configuración):

Usa tu talosconfig por defecto o genera uno con os:admin. Reserva esto para configuraciones donde se necesite explícitamente la capacidad de parchear la configuración.

Verificación de descargas

Sumas de verificación (integridad)

Cada versión incluye un archivo talos-mcp_<version>_checksums.txt con hashes SHA-256 de todos los archivos. Verifica el binario después de descargarlo:

# 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

Esto detecta la corrupción o descargas truncadas. No protege contra una tubería de lanzamiento comprometida.

Atestaciones de artefactos de GitHub (procedencia SLSA L2)

Cada versión incluye una atestación de procedencia de compilación nativa de GitHub que vincula criptográficamente el binario al commit específico y a la ejecución del flujo de trabajo que lo produjo:

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

Esto requiere la CLI de GitHub. Una verificación exitosa significa que el artefacto fue producido por el flujo de trabajo de lanzamiento oficial en este repositorio, no por una compilación de terceros.

Procedencia del paquete npm

El paquete npm se publica con atestación de procedencia:

npm audit signatures

Un resultado exitoso significa que el paquete fue publicado por el flujo de trabajo de lanzamiento oficial de GitHub Actions a través de publicación confiable OIDC.

Desarrollo

# Build
go build -o talos-mcp .

# Test
go test -race ./...

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

# Format check
gofmt -l .

Licencia

MIT