内容
talos-mcp
[](https://github.com/Nosmoht/talos-mcp-server/actions/workflows/ci.yml)
[](https://github.com/Nosmoht/talos-mcp-server/releases)
[](https://pkg.go.dev/github.com/Nosmoht/talos-mcp-server)
[](https://codecov.io/gh/Nosmoht/talos-mcp-server)
[](https://goreportcard.com/report/github.com/Nosmoht/talos-mcp-server)
[](https://scorecard.dev/viewer/?uri=github.com/Nosmoht/talos-mcp-server)
[](LICENSE)
一个暴露 Talos Linux 集群管理给 AI（如 Claude Code、OpenAI Codex 和任何兼容 MCP 的客户端）的 MCP 服务器。代替将 `talosctl` 的输出粘贴到聊天中，代理调用结构化的工具，直接从 Talos gRPC API 返回机器可读的 JSON — 中间输出的 token 成本为零。
通过使用与 `talosctl` 相同的 mTLS 凭证（`~/.talos/config`）连接到集群的原生 Talos gRPC API。
## 安装
**通过 npm**（无需 Go，Linux/macOS，amd64/arm64）：
```bash
npx talos-mcp
```
**通过 npm（全局安装）** 以便从 `$PATH` 持久调用：
```bash
npm install -g talos-mcp
```
安装二进制文件为 `<npm-prefix>/bin/talos-mcp`。验证：
```bash
which talos-mcp # 路径
talos-mcp # 版本 + 提交哈希
npm list -g talos-mcp # npm 对已安装
```
升级到最新发布的版本：
```npm install -g talos-mcp@latest
```
新版本在每次 `feat:` / `fix:` / `perf:`（或破坏性）合并到 `main` 后几分钟内出现在 npmjs.com — 请参阅 [CONTRIBUTING.md § 发布后发布管道](./CONTRIBUTING.md#post-merge-release-pipeline) 以了解机制。
**下载二进制文件**（Linux/macOS，amd64/arm64）：
从 [GitHub Releases](https://github.com/Nosmoht/talos-mcp-server/releases) 下载最新版本，解压二进制文件放在您的 `$PATH` 中。
**从源代码构建**（需要 Go 1.21+）：
```bash
git clone https://github.com/Nosmoht/talos-mcp-server
cdcp
go build -o talos-mcp ./cmd/talos-mcp
```
## 配置
默认读取 `~/.talos/config`（与 `talosctl` 使用的相同文件）。通过环境变量覆盖：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OSCONFIG` |/.talos/config` | talosconfig 文件| `TALOS_CONTEXT` | 活动使用的上下文名称 |
| `TALOS_ENDPOINTS` | 从配置 | 逗号分隔的端点覆盖 |
| `OS_MCP_READ_ONLY` | `false` | 设置为 `true` 以在启动时禁用所有变异工具 |
| `TALOS_MCP_HTTP_ADDR` | （未设置） | 如果设置（例如：`：8080`提供 Streamable HTTP 而不是 stdio |
|ALOS_MCP_AUTH_TOKEN` | （未设置 HTTP 模式活动时所需的 bearer token |
TALOS_MCP_ALLOWED_NODES` |设置） | 允许作为工具目标的 IP名和 CIDR 范围的逗号分隔未设置允许所有。 |
| `TALOS_MCP_ALLOWED_PATHS` | *（所有）* | `talos_read_file` 和 `tal_files` 允许的逗号分隔路径前缀（例如 `/etc,/proc`）。防御深度检查仅在 MCP 服务器主机上运行，**不** 在远程 Talos 节点上解析，因此在允许的前指向其他位置的符号链接不会被检测到| `TALOS_MCP_SKIP_VERSION_CHECK` | `false` | 设置为 `true` 以升级路径验证（例如用于工厂镜像或自定义标签） |
| `TALOS_MCP_ENABLE` | `false` | 在 `tal_config` / `talos_get` / `talos_version` / `talos_meta` 上解锁 `insecure=true`。绕过 mTLS — 需要 `TALCP_INSECURE_ALLOWED_NODES`。 |
| `TALOS_MCP_INSECURE_ALLOWED_NODES` | （未设置） | 允许在维护模式下作为 IP/CIDR 的逗号分隔列表。`TALOS_MCP_ENABLE_INSECURE=true` 时需要。拒绝：`0.0.0.0/0`，`::/0`，IPv4 掩码 `<16`，IPv6 掩码 `<48`。 |
| `TALOS_MCP_META_PRIVILEGED_KEYS` | *（无）* | `talos_meta` 允许写入/删除的 META 键（十进制或 `0x` 前缀的十六进制）的逗号分隔列表，超出 `User2/3`。 |
| `TALOS_MCP_SAF | （未设置） | `conservativestandard` / `expert` 预设门控标志。`expert` 启用 ``。 |
| `TALOS_MCP` | `10` | HTTP 模式：token-bucket 填充率（请求/秒数） |
| `TALOS_MCP_RATE_BURST` | `20` | HTTP 模式：token-b发容量（整数 `T_MCP_MAX_BODY_SIZE `4194304` | HTTP 模式 POST 请求正文字节）（默认B） |
| `OS_M_CONCURRENT` | | HTTP 最大并发 POST 处理程序（过载时快速失败 503） |
|ALOS_MION_RATE` | `1s`交付的 `resources 通知之间的 `(session, URI)` 对（Go `500ms| `T_MCP_SUBSCRIPTION_BURST`3` | ，每个 `(session)` 在速率开始生效之前 |
## 兼容性
该服务器已 Linux v1.x 至 v1.x 进行测试os-mcp | Linux | |-----------|-------------|---------------|
| v0.x（当前） | v9.0 –.13.x |.13.4连接的集群os 版本在测试会记录。使用的所有 RPC 方法自 v1.9 起稳定。
升级路径验证
_upgrade` 工具验证目标版本遵循 Tal支持升级路径 — 每次最多一个小例如 v1.11.x → v1.12.x）。跳过小版本的升级会被错误拒绝。
如果您的镜像使用自定义或工厂标签（例如 `factory.talos.dev/...` 或 `:latest`），则无法解析标签，验证会自动跳显式，请设置 `TALOS_M_CHECK=true`客户端设置
在mcp.json`
```json "m {
"": {
"npxargs": [" "talos"]
}
}
```
或在/.claude.json全局添加 `"Servers"`。如果本地二进制文件command":"` 替换文件的路径。
###
在 `/Application Support/Claude_desktop_config添加：
{
Servers": {
talos":command": " " ["-y",os-mcp"]
}
}
OpenAI Codexcodex/config.toml`（项目）/.codex（全局）中添加：
```[mcp_servers]
command =px"
args =", "talcp"]
[mcp_servers.talos.env]
TALOSCONFIG = "//talosconfig"
```
### 通用 MCP 客户端
服务器通过 stdio 使用 [MCP 协议](https://protocol.io)：
```bash
./talcp
```
## 工具
<!-- inventory -->
### 只读
| 工具|---|---|
| `talos_resource_definitions 列出所有可用的资源类型及其调用此命令以发现可以查询的内容。talos_get` | 获取或列出任意 COSI 资源类型（例如 `MachineStatus`、`Member`、`NodeAddress`、`Service`）。支持维护模式（`insecure=true` + `endpoint`）。 |
| `talos_version` |节点获取 Talos 版本信息。支持维护模式（`insecure=true` + `endpoint` `tal` | 列出所有 Talos 服务状态（运行中、停止、健康）。 |
| `talos_containers` | 列出命名空间（默认为 Kubernetes 容器的 `k8s.io`）中的容器。 |
| `talos_processes` | 列出目标正在运行。 |
| `talos_health` | 检查集群健康状况（etcd、Kubernetes API、节点就绪状态）。支持 `control_plane `worker_nodes` 覆盖。 |
| `talos_logs` | 获取最近的服务日志（最后 N 行，无跟随）。 |
| `talos_dmesg` | 读取内核环 |
| `talos_events` | Talos 运行时事件（服务更改）。 |
| `talos_etcd etcd 集群：`members`或 `status`。 |
| `_etcd_snapshot` | 将 etcd 快传输到本地文件路径。 |
|_list_files` | 列出节点文件系统上的文件和目录。 |
| `talos_read_file` | 从节点文件内容。 |
| `talos_validate` | 离线验证机器配置（YAML/JSON）— 无集群连接。 |
### 变异
这些工具会修改明确的安全防护。
| 工具 |护措施 |
|---|---|---|
| `_action` | 启动、停止或重启 Talos 服务（注意：不支持重启 `etcd 需要 `confirm=true` |
| `talos_reboot` | 重启目标节点。支持 `mode`：`default`、`powercycle`、`force`。 | 需要 `confirm=true`nodes` 必须显式 |
| `talos_upgrade` |目标节点上的 Talos。支持 `preserve`（默认 `true`）、`stage`、`force`、`reboot | 需要 `confirm=true`；` 和 `image` 需要 |
| `talos_rollback` | 回滚目标节点上的上 | 需要 `confirm=true`；` 必须显式 |
| `talos_patch_config` | 应用有针对性的机器配置战略合并或 RFC 6902 JSON 补丁）。 | `dry_run` 默认 `true`；`confirm=true` 在 `dry_run=false` 时需要 |
| `talos_reset` | 擦除并恢复出厂设置目标节点（不可逆）。 |=true`；`nodes` 必须显式 |
| `_config` | 将完整的机器配置应用于。支持维护模式（`insecure=true` + `endpoint`）用于新节点引导。 | `dry_run` 默认 `true`；`confirm `dry_run=false` 时需要 |
| `talos_meta` | 读取、写入或删除 META 分区键值对。支持维护模式（`in + `endpoint`）。 | `write`/`delete` 需要 `confirm；非 `UserReserved*` 键需要 `TALOS_MCP_META_PRIVILEGED_KEYS` 中枚举 inventory:tools:end -->
### 提示:prompts:start -->
| 提示 | 描述 |
|---|---|
| `diagnose-node` | 单个节点的诊断工作流程。 |
| `investigate-et | etcd 集群异常的重点调查。 |
| `debug-service` | 特定服务的诊断工作流程（kubelet、containerd、etcd、...）。 |
| `pre-upgrade-checklist` | Talos 升级。 |
| `apply-config` | 引导应用机器配置补丁仅在 `TALOS_MCP_READ_ONLY` 未设置时注册）。 |
<!-- inventory:prompts:end -->
### 资源和订阅
<!-- inventory:服务器将 Talos COSI 资源作为 MCP 资源公开：
- `://cluster/version` — 静态集群版本信息。
- `talos` — 发现资源类型。
- `talos://{resource/{namespace}/{type}[/{id}]` — 列出或获取特定节点 资源。
实现 `resources/subscribe` 的 MCP 客户端（Cl、Cursor）会在底层资源接收 `notifications/resources/updated` — 无需轮询。订阅由 TalI `Watch` / `WatchKindAggreg 流支持，并遵守相同的 `TALOS_MCP_ALLOWED_NODES` 允许列表。
可资源类型（规范名称）：
- `MachineStatuses.runtime.talos.dev` (`MachineStatus`)
- `Members.cluster.talos.dev`- `NodeAddresses.net.talos.dev` (`NodeAddress`)
- `Services.v1alpha1.talos.dev` (`Service`)
别名解析为规范类型，然后进行允许列表检查，因此客户端订阅 `talos://{node}/resource/runtime/ms/...`（`MachineStatus` 的别名）成功。其他 COSI 类型会以 `resource type %q is not subscribable` 拒绝。
传递速率按 `(session, URI)` 通过 `TALOS_MCP_SUBSCRIPTION_RATE` / `TALOS_MCP_SUBSCRIPTION_BURST` 限制；过量事件被丢弃，客户端重新读取资源以赶上。初始 `Bootstrapped` 事件故意不转发 — 客户端在订阅后应调用 `resources/read` 以获取初始状态。
<!-- inventory:resources:end -->
## 安全模型
### 信任边界
```
MCPClaude Code/Codex）
stdio/JSON-RPC
▼
talos-mcp ◄── 读取 TALOSCONFIG (~/.talos/config)
│ gRPC + mTLS
▼
Talos API（每个节点）
│
▼
节点 OS
```
**数据流警告：** 工具响应直接流入 LLM 的上下文窗口，并被发送到 LLM任何工具返回的内容 — IP、主机名、服务配置、内核日志、文件内容 —发送到您的 LLM 提供商勿将此包含您不愿意发送到您的 LLM 提供商的数据的集群一起使用。
**Talos RBAC 在服务器端强制执行。** 您的 talosconfig 中的凭证决定了每个节点上允许哪些操作。talos-mcp绕过 Talos RBAC — 如果 API 拒绝请求，它将以错误失败，而不是静默成功。
### 工具分类和最低要求的 RBAC | 工具 | RBAC 最低权限 |
|---|---|
| `_resource_definitions`、`talos_get`、`talos_version`、`talos_services`、`talos_containers`、`talos_processes`、`talos_health`、`talos_logs`、`talos`、`talos_events`、`talos_list_files`、`tal_file` | `os: |
| `talos_etcdos_service_action`、`talos_reboot`、`talos_upgradetalos_rollback` | `os:operator` |
| `talos_patch_config` | `os:admin` |
### 安全机制
| 机制 | 工作原理 |
|---|---|
| 只读模式 | `TALOS_M=true` 在启动时只读工具；变异不暴露给 LLM |
| 路列表 | `TALOS_PATHS=/etc,/proc` 将 `talos_read_file`os_list_files` 限制到指定的前缀。**防御深度，不是** 检查本地到 MCP 服务器 — 远程 Talos 节点上的解析到允许前缀之外不会。 |
| 确认门始终需要 `confirm=truetalos_service_action`、`talos_reboot`、`talos_upgrade`、`talos_rollback`、`talos_reset`。需要 `confirm=true` 且 `dry_run=false`：`talos_patch_config`、`talos_apply_config`。所有服务器端。 |
| 保留默认值 | `talos_upgrade` 默认 `preserve` 为 `true`（保留 EPHEMERAL 分区）— 与 `talosctl` 默认 `false` 不同 |
| 预览默认值 |os_patch_config` 默认 `dry_run；应用需要 `dry_run=false` 和 `confirm=true` |
| 审计日志 | 所有变异工具调用（`talos_service_action`、`talos_rebootos_upgrade`、`talrollback`、`talos_reset`、`talos_patch_config`、`talos_apply_config`）都会将结构化日志行输出到 stderr：`AUDIT timestamp=<RFC3339> tool=<name> nodes=<list> args=<json>`（补丁内容被遮蔽） |
### 威胁模型中未包含的内容
- **LLM 本身** — 提示注入、幻觉工具参数和 LLM 提供商的数据保留范围超出此服务器的范围
- **MCP 客户端** — Claude Code、Codex 或其他 MCP 客户端的安全性由其各自项目负责
- **talos-mcp 和 Talos 节点之间的网络路径** — 使用您的 talosconfig 中的凭证通过相互 TLS 保护
### 最小权限凭证设置
为使用此服务器创建具有最小权限的专用 talosconfig：
**只读访问（推荐用于大多数用例）：**
```bash
# 生成只读 talosconfig
talosctl config new --roles=os:reader talosconfig-readonly
```
然后设置 `TALOSCONFIG=/path/to/talosconfig-readonly` 和 `TALOS_MCP_READ_ONLY=true` 以实现最大限制。使用此设置，服务器仅公开只读工具，凭证无法执行任何变异操作，即使工具被绕过。
**操作员访问（用于服务管理、重启、升级）：**
```bash
talosctl config new --roles=os:operator talosconfig-operator
```
这涵盖了除 `talos_patch_config`（需要 `os:admin`）之外的所有工具。
**完全访问（需要配置修补）：**
使用默认 talosconfig 或使用 `os:admin` 生成一个。保留此设置仅适用于需要显式配置补丁功能的设置。
## 验证下载
### 校验和（完整性）
每个版本都包含一个 `talos-mcp_<version>_checksums.txt` 文件，其中包含所有存档的 SHA-256 哈希值。在下载后验证二进制文件：
```bash
# 下载存档和校验和
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
# 验证
sha256sum --check --ignore-missing talos-mcp_<version>_checksums.txt
```
这会检测损坏或截断的下载。它不会保护免受受损发布管道的影响。
### GitHub 工件声明（SLSA L2 来源证明）
每个版本都包含一个 GitHub 原生构建来源声明，该声明在加密上将二进制文件与生成它的特定提交和工作流运行链接：
```bash
gh attestation verify talos-mcp_<version>_linux_amd64.tar.gz \
--repo Nosmoht/talos-mcp-server
```
这需要 [GitHub CLI](https://cli.github.com/)。验证通过意味着该工件是由此存储库的官方发布工作流生成的，而不是第三方构建。
### npm 包来源
npm 包发布时附带来源声明：
```bash
npm audit signatures
```
通过的结果意味着该包是由官方 GitHub Actions 发布工作流通过 OIDC 受信任发布者发布的。
## 开发
```bash
# 构建
go build -o talos-mcp ./cmd/talos-mcp
# 测试
go test -race ./...
# lint（需要 golangci-lint v2）
golangci-lint run
# 格式检查
gofmt -l .
```
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器