talos-mcp

Release Go Reference codecov Go Report Card OpenSSF Scorecard License

一个将 Talos Linux 集群管理功能暴露给 AI 代理（Claude Code、OpenAI Codex 以及任何兼容 MCP 的客户端）的 MCP 服务器。代理无需将 talosctl 的输出粘贴到聊天中，而是直接调用结构化工具，从 Talos gRPC API 获取机器可读的 JSON —— 中间输出零 Token 成本。

使用与 talosctl (~/.talos/config) 相同的 mTLS 凭据，通过原生 Talos gRPC API 连接到您的集群。

安装

通过 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 客户端

该服务器通过 stdio 使用 MCP 协议：

./talos-mcp

工具

只读工具

工具	描述
`talos_resource_definitions`	列出所有可用的资源类型及其别名。首先调用此工具以发现可查询的内容。
`talos_get`	按类型获取或列出任何 COSI 资源（例如 `MachineStatus`、`Member`、`NodeAddress`、`Service`）。
`talos_version`	从目标节点获取 Talos 版本信息。
`talos_services`	列出所有 Talos 服务及其当前状态（运行中、已停止、健康状况）。
`talos_containers`	列出命名空间中的容器（默认：Kubernetes 容器为 `k8s.io`）。
`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 服务（注意：Talos API 不支持重启 `etcd`）。	—
`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 策略合并）。	`dry_run` 默认为 `true`；当 `dry_run=false` 时需要 `confirm=true`

所有工具都接受一个可选的 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 提供商的数据，请勿使用此服务器。

Talos RBAC 在服务端强制执行。 talosconfig 中的凭据决定了每个节点上允许的操作。talos-mcp 无法绕过 Talos RBAC —— 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 分区）—— 与 `talosctl` 默认的 `false` 不同
默认试运行	`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 节点之间的网络路径 —— 通过 talosconfig 中的凭据使用双向 TLS 保护

最小权限凭据设置

为配合此服务器使用，创建一个具有最小权限的专用 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 Artifact Attestations (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

验证通过意味着该包是通过 OIDC 可信发布由官方 GitHub Actions 发布工作流发布的。

开发

# 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