Talos MCP server for Talos Linux

io.github.sergelogvinovv0.2.0更新于 Oct 5, 2026

Talos MCP is an opinionated MCP server for Talos Linux

已验证STDIO仅桌面Cloud & Infrastructure Security & Monitoring

概览

AI 生成的概览

让 AI 助手通过 Talos API 检查 Talos Linux 集群与节点，读取版本、日志、事件和发现服务成员信息。

功能: 将 MCP 客户端连接到 Talos API（apid），并可选连接发现服务，支持多个集群并返回结构化数据。工具可列出已配置集群、描述集群节点的角色与版本、查看最近的运行时事件、列出发现服务成员，以及读取节点详情、服务日志和内核日志。显式启用后可提供一个重启节点的破坏性工具。
适用场景: 适合让助手收集和分析 Talos 集群信息，而不必手动执行大量 talosctl 命令，例如在变更基础设施之前。它不替代 Terraform、Ansible 或 GitOps，这些工具仍是基础设施变更的主要来源。
运行要求: 以 stdio 本地进程运行（可通过 Homebrew 或容器镜像安装）。需要 talosconfig 文件，通过 --talosconfig 或 TALOSCONFIG 指定，并为每个集群配置凭据；加密字段需要解锁来源，如 TALOSCONFIG_IDENTITY、TALOSCONFIG_PASSPHRASE_FILE 或 TALOSCONFIG_ASKPASS。需要访问 Talos API 端点的网络。也提供 HTTP 服务器模式。

安装前请注意

talosconfig 包含私钥，若使用发现服务还包含 cluster_secret；应加密存储并限制文件访问。默认工具为只读，但 --allow-destructive 会启用 talos_node_reboot，该工具会重启节点并在节点恢复前返回。HTTP 端点没有用户认证，所有调用者都使用服务器的凭据；请用网络策略或认证代理保护它。

安装

在 SourceWeft 中

打开控制台中的 Talos MCP server for Talos Linux，将其添加到工作区。
为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照仓库中的启动说明。

README

Talos opinionated MCP Server

NOTE: This project is under active development.

Motivation

Modern infrastructure often uses tools such as Terraform/OpenTofu, Ansible, and GitOps. These tools deploy and configure Talos Linux nodes and Kubernetes clusters.

The Talos MCP Server does not replace these tools. It gives AI assistants and automation agents access to information about your Talos clusters.

The default tools are read-only. An optional action tool can be enabled with --allow-destructive to reboot a node.

Instead of running many talosctl commands across nodes, you can ask an AI assistant to collect and analyze the required information. Your existing automation tools remain the main source for infrastructure changes.

Overview

The server connects an MCP client, such as an AI assistant, to the Talos API (apid) and, optionally, to the Talos discovery service. It supports multiple Talos clusters and returns structured data.

You can use it to:

inspect clusters, nodes, and their Talos and Kubernetes versions
read Talos service logs and kernel logs (dmesg) of a node
review recent Talos runtime events
list cluster members from the discovery service, even when the Talos API is down
collect information before you make infrastructure changes

Keep your AI on the leash.

Talos tools

The MCP server provides the following tools:

Tool	Arguments	Description
`talos_clusters_list`	None	List the configured clusters with their endpoints, credential role, and the tools usable on each. Makes no network calls.
`talos_clusters_describe`	`cluster` (optional)	Show every node of a cluster with its role and Talos and kubelet versions.
`talos_clusters_event`	`cluster`, `node`, `since`, `limit`, `actor_id` (all optional)	List recent Talos runtime events, newest first. Defaults: last `1h`, `50` events.
`talos_clusters_members`	`cluster`, `role` (optional)	List cluster members as the discovery service sees them: node ID, hostname, role, addresses, and KubeSpan data. Available only on clusters with discovery keys.
`talos_node_describe`	`cluster`, `node`, `logs`, `log_lines`, `events_since`, `event_limit` (all optional)	Show one node in detail: versions, stage and readiness, resource usage (CPU, load, memory, disks, top processes), every service's state and health, recent events, and the last log lines of the unhealthy services. Secrets in the output are masked.
`talos_node_logs`	`service`, `cluster`, `node`, `kubernetes`, `tail`, `grep` (optional except `service`)	Show the last lines of a Talos service's logs (`kubelet`, `etcd`, `apid`, `machined`, ...) or of a Kubernetes container.
`talos_node_dmesg`	`cluster`, `node`, `tail`, `grep` (all optional)	Show the last lines of a node's kernel log. Secrets in the output are masked.

cluster is a talosconfig context name. When it is omitted, the current context is used. Use talos_clusters_list first to find the cluster names. MCP clients can discover the full input and output schemas. You can also list the tools from the command line:

When --allow-destructive is enabled and the cluster's credential has the os:operator role, talos_node_reboot accepts cluster, node, and an optional mode (default or powercycle). It returns once Talos accepts the request; it does not wait for the node to come back.

The tools available on each cluster depend on the role of its client certificate: os:reader gets the read-only tools, os:operator also gets the reboot tool.

Installation

For a local installation with Homebrew, run:

You do not need a local installation when you use an MCP server hosted on another machine.

Configure Talos clusters

The server reads a standard talosconfig, the same file talosctl uses. Each context is one cluster. Create a dedicated credential with the smallest role you need:

A context may also have an optional discovery block with the cluster ID and secret, which enables talos_clusters_members:

yaml

context: prod-eucontexts:  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...

context: prod-eucontexts:  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...

The private key and cluster_secret can be stored encrypted with a passphrase, an age key, or your SSH key:

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

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

Set the talosconfig path with --talosconfig or TALOSCONFIG. The default is ~/.talos/config.

See docs/config.md for every talosconfig field, the discovery block, credential roles, the unlock options for encrypted secrets, the config import, encrypt, decrypt, and check commands, deployment recipes, and troubleshooting.

Configure an MCP client

Local stdio server

For clients that use a JSON MCP configuration, add an entry like this:

json

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

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

If the talosconfig has encrypted fields, also set an unlock source, for example "TALOSCONFIG_IDENTITY": "/absolute/path/to/.ssh/id_ed25519". The mcp command never prompts for a passphrase.

Remote HTTP server

Start the streamable HTTP server with:

The MCP endpoint is http://host:8080/mcp, and a health check is served on /healthz.

For a remote client, use an HTTPS URL that ends with /mcp:

json

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

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

The server does not provide user authentication for the HTTP endpoint. Every caller uses the credentials from the server's talosconfig, so protect the endpoint with a network policy or an authenticating proxy.

A Helm chart for Kubernetes is available in charts/talos-mcp.

Restart or reload the MCP client after you save its configuration.

Running

Common flags

The mcp, server, and tools commands use the following flags. Each flag can also be set with an environment variable. A command-line flag has higher priority than an environment variable.

Flag	Environment variable	Default	Description
`--talosconfig <path>`	`TALOSCONFIG`	`~/.talos/config`	Path to the talosconfig file.
`--context <name>`	`TALOS_CONTEXT`	All contexts	Use only this one talosconfig context.
`--talosconfig-identity <path>`	`TALOSCONFIG_IDENTITY`	None	age identity or OpenSSH private key that decrypts encrypted fields. Repeatable.
`--talosconfig-passphrase-file <path>`	`TALOSCONFIG_PASSPHRASE_FILE`	None	File with the passphrase of encrypted fields.
`--talosconfig-askpass <program>`	`TALOSCONFIG_ASKPASS`	None	Program that prints the passphrase of encrypted fields.
`--extensions <list>`	`EXTENSIONS`	`all`	Comma-separated tool groups to enable: `cluster`, `node`, or `all`.
`--allow-destructive`	`ALLOW_DESTRUCTIVE`	`false`	Allow destructive tools, such as `talos_node_reboot`.
`--log-level <level>`	`LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, or `error`.
`--log-format <format>`	`LOG_FORMAT`	`text`	Log output format: `text` or `json`.

The server command also accepts --listen-address (LISTEN_ADDRESS, default 127.0.0.1:8080) and --require-all-contexts (REQUIRE_ALL_CONTEXTS). The container image sets LISTEN_ADDRESS=:8080. The tools command accepts --output (-o) with text, json, or yaml. Its default is text.

For example, run the stdio server with JSON logs:

Test the configuration

Check the talosconfig and its encrypted fields:

List all available tools:

Call a tool directly:

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

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

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

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

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Talos Linux is a trademark of Sidero Labs, Inc.

来源：README.md，提交 ed32ca8

工具

工具元数据尚未被收录。

版本历史

v0.2.0最新Oct 5, 2026