Talos Linux Mcp Server

talos-mcp

一个 MCP 服务，可向 AI Agent（Claude Code、OpenAI Codex 以及任何兼容 MCP 的客户端）提供 Talos Linux 集群管理功能。无需将 talosctl 输出粘贴到聊天中，Agent 可以调用结构化工具，直接从 Talos gRPC API 获取机器可读的 JSON——中间输出不会消耗 token。

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

安装

通过 npm 安装（无需 Go，适用于 Linux/macOS、amd64/arm64）：

npx talos-mcp

通过 npm 全局安装，以便从 $PATH 中持续调用：

npm install -g talos-mcp

该命令会将二进制文件安装为 <npm-prefix>/bin/talos-mcp。使用以下命令验证：

which talos-mcp        # path
talos-mcp --version    # version + commit hash
npm list -g talos-mcp  # npm's view of the installed version

升级到最新发布版本：

npm install -g talos-mcp@latest

每次将 feat: / fix: / perf:（或破坏性变更）合并到 main 后，几分钟内新版本就会发布到 npmjs.com——发布机制请参阅 CONTRIBUTING.md § 合并后发布流程。

下载二进制文件（适用于 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 ./cmd/talos-mcp

配置

默认读取 ~/.talos/config（与 talosctl 使用的文件相同）。可通过环境变量覆盖：

变量	默认值	说明
TALOSCONFIG	~/.talos/config	talosconfig 文件的路径
TALOS_CONTEXT	active context	要使用的上下文名称
TALOS_ENDPOINTS	from config	以逗号分隔的端点覆盖列表
TALOS_MCP_READ_ONLY	false	设置为 true 可在启动时禁用所有会修改状态的工具
TALOS_MCP_HTTP_ADDR	(unset)	若已设置（例如 :8080），则提供 Streamable HTTP 服务，而非 stdio
TALOS_MCP_AUTH_TOKEN	(unset)	HTTP 模式启用时所需的 bearer token
TALOS_MCP_ALLOWED_NODES	(unset)	允许作为工具目标的 IP、主机名和 CIDR 范围，以逗号分隔。未设置时允许所有目标。
TALOS_MCP_ALLOWED_PATHS	(all)	talos_read_file 和 talos_list_files 允许访问的路径前缀，以逗号分隔（例如 /etc,/proc）。仅作为纵深防御措施——检查在 MCP 服务主机上运行，不会解析远程 Talos 节点上的符号链接，因此无法检测指向其他位置的允许前缀下的符号链接。
TALOS_MCP_SKIP_VERSION_CHECK	false	设置为 true 可跳过升级路径验证（例如，用于工厂镜像或自定义标签）
TALOS_MCP_ENABLE_INSECURE	false	解锁 talos_apply_config / talos_get / talos_version / talos_meta 上的 insecure=true。绕过 mTLS——必须设置 TALOS_MCP_INSECURE_ALLOWED_NODES。
TALOS_MCP_INSECURE_ALLOWED_NODES	(unset)	允许作为维护模式端点的 IP / CIDR 范围，以逗号分隔。设置 TALOS_MCP_ENABLE_INSECURE=true 时必须配置。拒绝：0.0.0.0/0、::/0、IPv4 掩码 <16、IPv6 掩码 <48。
TALOS_MCP_META_PRIVILEGED_KEYS	(none)	talos_meta 除 UserReserved1/2/3 外允许写入/删除的 META 键，以逗号分隔（十进制或带 0x 前缀的十六进制）。
TALOS_MCP_SAFETY_PROFILE	(unset)	conservative / standard / expert 预设，用于初始化门控标志。expert 会启用 EnableInsecure。
TALOS_MCP_RATE_LIMIT	10	HTTP 模式：令牌桶补充速率（请求/秒，浮点数）
TALOS_MCP_RATE_BURST	20	HTTP 模式：令牌桶突发容量（整数）
TALOS_MCP_MAX_BODY_SIZE	4194304	HTTP 模式：POST 请求正文的最大字节数（默认 4 MiB）
TALOS_MCP_MAX_CONCURRENT	20	HTTP 模式：并发 POST 处理程序的最大数量（过载时快速返回 503）
TALOS_MCP_SUBSCRIPTION_RATE	1s	每对 (session, URI) 发送 resources/updated 通知的最小间隔（Go 时长，例如 500ms）
TALOS_MCP_SUBSCRIPTION_BURST	3	速率限制生效前，每对 (session, URI) 的初始通知突发数量

兼容性

此服务已通过 Talos Linux v1.9.x 至 v1.13.x 的测试。

talos-mcp	Talos Linux	machinery SDK
v0.x (current)	v1.9.0 – v1.13.x	v1.13.4

如果连接的集群所用 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 协议：

./talos-mcp

工具

只读

工具	描述
talos_resource_definitions	列出所有可用的资源类型及其别名。请先调用此工具，以了解可以查询哪些内容。
talos_get	按类型获取或列出任意 COSI 资源（例如 MachineStatus、Member、NodeAddress、Service）。支持维护模式（insecure=true + endpoint）。
talos_version	获取目标节点的 Talos 版本信息。支持维护模式（insecure=true + endpoint）。
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_etcd_snapshot	将 etcd 快照流式写入本地文件路径。
talos_list_files	列出节点文件系统中的文件和目录。
talos_read_file	读取节点文件系统中的文件内容。
talos_validate	离线校验机器配置（YAML/JSON）——无需连接集群。

修改类

这些工具会修改集群状态，并设有明确的安全保护措施。

工具	描述	保护措施
talos_service_action	启动、停止或重启 Talos 服务（注意：Talos API 不支持重启 etcd）。	必须设置 confirm=true
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	应用定向机器配置补丁（strategic-merge 或 RFC 6902 JSON Patch）。	dry_run 默认为 true；当 dry_run=false 时，必须设置 confirm=true
talos_reset	清除目标节点并恢复出厂设置（不可逆）。	必须设置 confirm=true；必须明确指定 nodes
talos_apply_config	为单个节点应用完整机器配置。支持维护模式（insecure=true + endpoint），用于新节点引导。	dry_run 默认为 true；当 dry_run=false 时，必须设置 confirm=true
talos_meta	读取、写入或删除 META 分区键值对。支持维护模式（insecure=true + endpoint）。	write / delete 必须设置 confirm=true；非 UserReserved* 键必须列入 TALOS_MCP_META_PRIVILEGED_KEYS

所有工具都接受可选的 nodes 字段（节点 IP 地址或主机名列表）。省略时，将使用 talosconfig 中的活动上下文。

维护模式（--insecure）操作

talos_apply_config、talos_get、talos_version 和 talos_meta 接受 insecure=true 标志，用于访问处于维护模式的节点（已启动但尚未配置）。传输经过 TLS 加密，但绕过 mTLS——没有客户端证书，且（默认情况下）不验证服务端证书。这是引导全新节点所必需的（等同于 talosctl apply-config --insecure）。

• 必须由操作员主动启用。 设置 TALOS_MCP_ENABLE_INSECURE=true（或使用 expert 安全配置）。否则，所有 insecure=true 调用都会被拒绝。
• 必须配置端点允许列表。 将允许访问的维护模式 IP / CIDR 列表（以逗号分隔）设置到 TALOS_MCP_INSECURE_ALLOWED_NODES。如果缺少该设置，或包含 0.0.0.0/0、::/0、小于 <16 的 IPv4 掩码或小于 <48 的 IPv6 掩码，则启动会中止。在生产环境中请使用 /28 或更窄的网段。
• 端点必须是纯 IP。 不允许主机名、host:port、协议方案或 IPv6 区域。链路本地地址（包括 169.254.169.254 IMDS）、环回地址、多播地址和未指定地址均会被拒绝。
• 通过 TOFU 固定证书缓解 MITM。 传入 cert_fingerprint=<64-hex>（从 Talos 控制台横幅复制的服务端 SHA-256 指纹），以启用叶证书验证。若不提供该参数，MCP 服务与目标节点之间路径上的任何人都可以实施 MITM 攻击。
• META 写入/删除安全列表。 talos_meta 的写入/删除操作仅限于 meta.UserReserved1/2/3。必须在 TALOS_MCP_META_PRIVILEGED_KEYS 中逐个列出特权键（如 Upgrade、StateEncryptionConfig 等），不能使用一刀切的标志。

提示词

提示词	描述
diagnose-node	针对单个节点的引导式诊断工作流。
investigate-etcd	针对 etcd 集群异常的专项调查。
debug-service	针对特定服务（kubelet、containerd、etcd 等）的诊断工作流。
pre-upgrade-checklist	Talos 升级前的预检验证。
apply-config	应用机器配置补丁的引导式流程（仅在未设置 TALOS_MCP_READ_ONLY 时注册）。

资源和订阅

服务会将 Talos COSI 资源作为 MCP 资源公开：

• talos://cluster/version — 静态集群版本信息。
• talos://cluster/resource-definitions — 发现资源类型。
• talos://{node}/resource/{namespace}/{type}[/{id}] — 列出或获取特定节点上的 COSI 资源。

实现了 resources/subscribe 的 MCP 客户端（Claude Desktop、Cursor）会在底层资源发生变化时收到 notifications/resources/updated 通知——无需轮询。订阅由 Talos COSI Watch / WatchKindAggregated 流提供支持，并遵循与读取相同的 TALOS_MCP_ALLOWED_NODES 允许列表。

可订阅的资源类型（规范名称）：

• MachineStatuses.runtime.talos.dev（MachineStatus）
• Members.cluster.talos.dev（Member）
• NodeAddresses.net.talos.dev（NodeAddress）
• Services.v1alpha1.talos.dev（Service）

在检查允许列表之前，会先将别名解析为规范类型，因此客户端订阅 talos://{node}/resource/runtime/ms/...（MachineStatus 的别名）会成功。其他 COSI 类型会返回 resource type %q is not subscribable。静态 talos://cluster/* URI 不可订阅（没有 COSI 后端支持）。

通过 TALOS_MCP_SUBSCRIPTION_RATE / TALOS_MCP_SUBSCRIPTION_BURST 对每个 (session, URI) 的事件投递进行速率限制；超出速率的事件会被丢弃，客户端需重新读取资源以追上最新状态。初始的 Bootstrapped 事件不会转发——预期客户端在订阅后调用一次 resources/read 以获取初始状态。

安全模型

信任边界

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

**数据流警告：**工具响应会直接流入大模型的上下文窗口，并发送给大模型提供商。工具返回的任何内容——节点 IP、主机名、服务配置、内核日志、文件内容——都会成为通过网络发送的提示词的一部分。请勿将此服务用于包含您不愿发送给大模型提供商的数据的集群。

**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 会在启动时仅注册只读工具；不会向大模型暴露可变更工具
路径允许列表	TALOS_MCP_ALLOWED_PATHS=/etc,/proc 将 talos_read_file 和 talos_list_files 的访问范围限制在指定前缀内。**纵深防御措施，而非严格边界：**检查在 MCP 服务本地进行——无法检测远程 Talos 节点上解析到允许前缀之外的符号链接。
确认门槛	始终要求 confirm=true：talos_service_action、talos_reboot、talos_upgrade、talos_rollback、talos_reset。当 dry_run=false 时，要求 confirm=true：talos_patch_config、talos_apply_config。所有检查均在服务端强制执行。
保留默认值	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_reset、talos_patch_config、talos_apply_config）都会向 stderr 输出结构化日志行：AUDIT timestamp=<RFC3339> tool=<name> nodes=<list> args=<json>（补丁内容会被脱敏）

威胁模型不包含的内容

• 大模型本身——提示词注入、幻觉生成的工具参数，以及大模型提供商的数据保留均不在此服务的范围内
• 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 Package Provenance（npm 包来源证明）

npm 包发布时附带来源证明：

npm audit signatures

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

开发

# Build
go build -o talos-mcp ./cmd/talos-mcp

# Test
go test -race ./...

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

# Format check
gofmt -l .

许可证

MIT