Talos MCP server for Talos Linux

Talos 意见导向型 MCP 服务

NOTE： 此项目正在积极开发中。

动机

现代基础设施通常使用 Terraform/OpenTofu、Ansible 和 GitOps 等工具。这些工具用于部署和配置 Talos Linux 节点与 Kubernetes 集群。

Talos MCP 服务不会取代这些工具，而是让 AI 助手和自动化 Agent 能够访问 Talos 集群的信息。

默认工具为只读工具。可以通过 --allow-destructive 启用一个可选的操作工具，以重启节点。

你不必在多个节点上运行大量 talosctl 命令，而是可以让 AI 助手收集并分析所需信息。现有的自动化工具仍是进行基础设施变更的主要途径。

概述

此服务将 MCP 客户端（例如 AI 助手）连接到 Talos API (apid)，并可选地连接到 Talos 发现服务。它支持多个 Talos 集群，并返回结构化数据。

你可以使用它来：

• 检查集群、节点及其 Talos 和 Kubernetes 版本
• 读取节点的 Talos 服务日志和内核日志 (dmesg)
• 查看近期的 Talos 运行时事件
• 即使 Talos API 不可用，也能从发现服务列出集群成员
• 在进行基础设施变更前收集信息

管好你的 AI。

Talos 工具

MCP 服务提供以下工具：

工具	参数	描述
talos_clusters_list	无	列出已配置的集群及其端点、凭证角色，以及每个集群可使用的工具。不进行网络调用。
talos_clusters_describe	cluster（可选）	显示集群中的每个节点及其角色、Talos 和 kubelet 版本。
talos_clusters_event	cluster、node、since、limit、actor_id（均可选）	按时间从近到远列出近期的 Talos 运行时事件。默认值：最近 1h 内的 50 个事件。
talos_clusters_members	cluster、role（可选）	按发现服务所见列出集群成员：节点 ID、主机名、角色、地址和 KubeSpan 数据。仅适用于配置了发现密钥的集群。
talos_node_describe	cluster、node、logs、log_lines、events_since、event_limit（均可选）	详细显示单个节点的信息：版本、阶段和就绪状态、资源使用情况（CPU、负载、内存、磁盘、占用资源最多的进程）、所有服务的状态和运行状况、近期事件，以及运行状况不佳的服务的最新日志行。输出中的机密信息会被屏蔽。
talos_node_logs	service、cluster、node、kubernetes、tail、grep（除 service 外均可选）	显示 Talos 服务（kubelet、etcd、apid、machined 等）或 Kubernetes 容器的最新日志行。
talos_node_dmesg	cluster、node、tail、grep（均可选）	显示节点内核日志的最新行。输出中的机密信息会被屏蔽。

cluster 是 talosconfig 上下文名称。省略时，将使用当前上下文。请先使用 talos_clusters_list 查找集群名称。MCP 客户端可以发现完整的输入和输出架构。你也可以在命令行中列出工具：

talos-mcp tools --talosconfig /absolute/path/to/talosconfig

启用 --allow-destructive，且集群凭证具有 os:operator 角色时，talos_node_reboot 接受 cluster、node 和可选的 mode（default 或 powercycle）。Talos 接受请求后，此工具便会返回；它不会等待节点重新上线。

每个集群可用的工具取决于其客户端证书的角色：os:reader 可使用只读工具，os:operator 还可使用重启工具。

安装

如需通过 Homebrew 在本地安装，请运行：

brew install sergelogvinov/tap/talos-mcp

使用托管在另一台机器上的 MCP 服务时，无需在本地安装。

配置 Talos 集群

服务会读取标准的 talosconfig，与 talosctl 使用的是同一个文件。 每个上下文对应一个集群。请创建一个专用凭据，并赋予所需的最低角色：

talosctl config new --roles os:reader --crt-ttl 8760h ~/.talos/mcp-config

上下文还可以包含可选的 discovery 块，其中包含集群 ID 和密钥， 用于启用 talos_clusters_members：

context: prod-eu
contexts:
  prod-eu:
    endpoints: [10.0.0.10, 10.0.0.11, 10.0.0.12]
    ca: LS0t...
    crt: LS0t...
    key: LS0t...
    discovery:
      cluster_id: 3x9y...
      cluster_secret: c2VjcmV0...

私有 key 和 cluster_secret 可以使用密码短语、age 密钥或 SSH 密钥加密存储：

talos-mcp config encrypt --talosconfig ~/.talos/mcp-config -o ~/.talos/mcp-config.enc \
    --recipient-file ~/.ssh/id_ed25519.pub
talos-mcp config check --talosconfig ~/.talos/mcp-config.enc \
    --talosconfig-identity ~/.ssh/id_ed25519

使用 --talosconfig 或 TALOSCONFIG 设置 talosconfig 路径。默认路径为 ~/.talos/config。

请参阅 docs/config.md，了解所有 talosconfig 字段、discovery 块、凭据角色、加密密钥的解锁选项、 config import、encrypt、decrypt 和 check 命令、部署方案以及 故障排除。

配置 MCP 客户端

本地 stdio 服务

对于使用 JSON MCP 配置的客户端，请添加类似以下内容的条目：

{
  "mcpServers": {
    "talos": {
      "command": "talos-mcp",
      "args": ["mcp"],
      "env": {
        "TALOSCONFIG": "/absolute/path/to/talosconfig"
      }
    }
  }
}

如果 talosconfig 包含加密字段，还需设置解锁来源，例如 "TALOSCONFIG_IDENTITY": "/absolute/path/to/.ssh/id_ed25519"。 mcp 命令不会提示输入密码短语。

远程 HTTP 服务

使用以下命令启动流式 HTTP 服务：

talos-mcp server \
  --talosconfig /absolute/path/to/talosconfig \
  --listen-address :8080

MCP 端点为 http://host:8080/mcp，健康检查端点为 /healthz。

对于远程客户端，请使用以 /mcp 结尾的 HTTPS URL：

{
  "mcpServers": {
    "talos": {
      "type": "http",
      "url": "https://talos-mcp.example.com/mcp"
    }
  }
}

该服务不会为 HTTP 端点提供用户身份验证。所有调用方都会使用服务端 talosconfig 中的凭据，因此请使用网络策略或身份验证代理来保护端点。

Kubernetes 的 Helm 图表位于 charts/talos-mcp。

保存配置后，请重启或重新加载 MCP 客户端。

运行

常用标志

mcp、server 和 tools 命令使用以下标志。每个标志 也可以通过环境变量设置。命令行标志的优先级高于环境变量。

标志	环境变量	默认值	说明
--talosconfig <path>	TALOSCONFIG	~/.talos/config	talosconfig 文件的路径。
--context <name>	TALOS_CONTEXT	所有上下文	仅使用此 talosconfig 上下文。
--talosconfig-identity <path>	TALOSCONFIG_IDENTITY	无	用于解密加密字段的 age 身份或 OpenSSH 私钥。可重复指定。
--talosconfig-passphrase-file <path>	TALOSCONFIG_PASSPHRASE_FILE	无	包含加密字段密码短语的文件。
--talosconfig-askpass <program>	TALOSCONFIG_ASKPASS	无	用于输出加密字段密码短语的程序。
--extensions <list>	EXTENSIONS	all	以逗号分隔的要启用的工具组：cluster、node 或 all。
--allow-destructive	ALLOW_DESTRUCTIVE	false	允许使用破坏性工具，例如 talos_node_reboot。
--log-level <level>	LOG_LEVEL	info	日志级别：debug、info、warn 或 error。
--log-format <format>	LOG_FORMAT	text	日志输出格式：text 或 json。

server 命令还接受 --listen-address（LISTEN_ADDRESS， 默认值为 127.0.0.1:8080）和 --require-all-contexts （REQUIRE_ALL_CONTEXTS）。容器镜像将 LISTEN_ADDRESS 设为 :8080。tools 命令接受 --output（-o），取值为 text、json 或 yaml。默认值为 text。

例如，使用 JSON 日志运行 stdio 服务：

talos-mcp mcp \
  --talosconfig /absolute/path/to/talosconfig \
  --log-format json

测试配置

检查 talosconfig 及其加密字段：

talos-mcp config check --talosconfig /absolute/path/to/talosconfig

列出所有可用工具：

export TALOSCONFIG="/absolute/path/to/talosconfig"
talos-mcp tools

直接调用工具：

talos-mcp tools talos_clusters_list
talos-mcp tools talos_clusters_describe cluster=prod-eu
talos-mcp tools -o json talos_node_logs cluster=prod-eu node=10.0.0.10 service=kubelet tail=50

许可证

本软件根据 Apache License 2.0 版（以下简称“许可证”）授权； 除非遵守许可证，否则不得使用此文件。 您可以在此处获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或经书面同意，根据许可证分发的软件均按“原样”提供， 不附带任何明示或暗示的保证或条件。 请参阅许可证，了解管理权限和限制的特定语言。

---

Talos Linux 是 Sidero Labs, Inc. 的商标