# Talos Linux MCP Server

> MCP server for Talos Linux — resources, services, logs, health, config, lifecycle via gRPC.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nosmoht-talos-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Nosmoht](https://agentstack.voostack.com/s/nosmoht)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 2.3.1
- **License:** MIT
- **Upstream author:** [Nosmoht](https://github.com/Nosmoht)
- **Source:** https://github.com/Nosmoht/talos-mcp-server

## Install

```sh
agentstack add mcp-nosmoht-talos-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

An MCP server that exposes Talos Linux cluster management to AI agents (Claude Code, OpenAI Codex, and any MCP-compatible client). Instead of pasting `talosctl` output into chat, the agent calls structured tools that return machine-readable JSON directly from the Talos gRPC API — zero token cost for intermediate output.

Connects to your cluster via the native Talos gRPC API using the same mTLS credentials as `talosctl` (`~/.talos/config`).

## Installation

**Via npm** (no Go required, Linux/macOS, amd64/arm64):

```bash
npx talos-mcp
```

**Via npm (global install)** for persistent invocation from `$PATH`:

```bash
npm install -g talos-mcp
```

Installs the binary as `/bin/talos-mcp`. Verify with:

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

Upgrade to the latest published release:

```bash
npm install -g talos-mcp@latest
```

New releases appear on npmjs.com within minutes of every `feat:` / `fix:` / `perf:` (or breaking) merge to `main` — see [CONTRIBUTING.md § Post-merge release pipeline](./CONTRIBUTING.md#post-merge-release-pipeline) for the mechanism.

**Download binary** (Linux/macOS, amd64/arm64):

Download the latest release from [GitHub Releases](https://github.com/Nosmoht/talos-mcp-server/releases), extract, and place the binary in your `$PATH`.

**Build from source** (requires Go 1.21+):

```bash
git clone https://github.com/Nosmoht/talos-mcp-server
cd talos-mcp
go build -o talos-mcp ./cmd/talos-mcp
```

## Configuration

Reads `~/.talos/config` by default (the same file `talosctl` uses). Override via environment variables:

| Variable | Default | Description |
|---|---|---|
| `TALOSCONFIG` | `~/.talos/config` | Path to talosconfig file |
| `TALOS_CONTEXT` | active context | Context name to use |
| `TALOS_ENDPOINTS` | from config | Comma-separated endpoint overrides |
| `TALOS_MCP_READ_ONLY` | `false` | Set to `true` to disable all mutating tools at startup |
| `TALOS_MCP_HTTP_ADDR` | (unset) | If set (e.g. `:8080`), serve Streamable HTTP instead of stdio |
| `TALOS_MCP_AUTH_TOKEN` | (unset) | Required bearer token when HTTP mode is active |
| `TALOS_MCP_ALLOWED_NODES` | (unset) | Comma-separated IPs, hostnames, and CIDR ranges permitted as tool targets. Unset allows all. |
| `TALOS_MCP_ALLOWED_PATHS` | *(all)* | Comma-separated path prefixes allowed for `talos_read_file` and `talos_list_files` (e.g. `/etc,/proc`). Defense-in-depth only — checks run on the MCP server host and do **not** resolve symlinks on the remote Talos node, so a symlink under an allowed prefix that points elsewhere is not detected. |
| `TALOS_MCP_SKIP_VERSION_CHECK` | `false` | Set to `true` to bypass upgrade path validation (e.g. for factory images or custom tags) |
| `TALOS_MCP_ENABLE_INSECURE` | `false` | Unlock `insecure=true` on `talos_apply_config` / `talos_get` / `talos_version` / `talos_meta`. Bypasses mTLS — REQUIRES `TALOS_MCP_INSECURE_ALLOWED_NODES`. |
| `TALOS_MCP_INSECURE_ALLOWED_NODES` | (unset) | Comma-separated IPs / CIDRs permitted as maintenance-mode endpoints. Required when `TALOS_MCP_ENABLE_INSECURE=true`. Refused: `0.0.0.0/0`, `::/0`, IPv4 mask `` (server SHA-256 fingerprint, copied from the Talos console banner) to enable leaf-cert verification. Without it, the connection is MITMable by anyone on-path between the MCP server and the target node.
- **META write/delete safelist.** `talos_meta` write/delete is restricted to `meta.UserReserved1`/`2`/`3`. Privileged keys (`Upgrade`, `StateEncryptionConfig`, …) must be enumerated in `TALOS_MCP_META_PRIVILEGED_KEYS` (per-key, not a blanket flag).

### Prompts

| Prompt | Description |
|---|---|
| `diagnose-node` | Guided diagnosis workflow for a single node. |
| `investigate-etcd` | Focused investigation of an etcd cluster anomaly. |
| `debug-service` | Service-specific diagnostic workflow (kubelet, containerd, etcd, …). |
| `pre-upgrade-checklist` | Pre-flight verification before a Talos upgrade. |
| `apply-config` | Guided flow for applying a machine config patch (registered only when `TALOS_MCP_READ_ONLY` is unset). |

### Resources and Subscriptions

The server exposes Talos COSI resources as MCP resources:

- `talos://cluster/version` — static cluster version info.
- `talos://cluster/resource-definitions` — discover resource types.
- `talos://{node}/resource/{namespace}/{type}[/{id}]` — list or get COSI resources on a specific node.

MCP clients that implement `resources/subscribe` (Claude Desktop, Cursor) receive `notifications/resources/updated` whenever the underlying resource changes — no polling required. Subscriptions are backed by the Talos COSI `Watch` / `WatchKindAggregated` streams and honour the same `TALOS_MCP_ALLOWED_NODES` allowlist as reads.

Subscribable resource types (canonical names):

- `MachineStatuses.runtime.talos.dev` (`MachineStatus`)
- `Members.cluster.talos.dev` (`Member`)
- `NodeAddresses.net.talos.dev` (`NodeAddress`)
- `Services.v1alpha1.talos.dev` (`Service`)

Aliases resolve to the canonical type before the allowlist check, so a client subscribing to `talos://{node}/resource/runtime/ms/...` (alias for `MachineStatus`) succeeds. Other COSI types reject with `resource type %q is not subscribable`. Static `talos://cluster/*` URIs are not subscribable (no COSI backing).

Delivery is rate-limited per `(session, URI)` via `TALOS_MCP_SUBSCRIPTION_RATE` / `TALOS_MCP_SUBSCRIPTION_BURST`; over-rate events are dropped and the client re-reads the resource to catch up. The initial `Bootstrapped` event is intentionally not forwarded — the client is expected to call `resources/read` once after subscribe for initial state.

## Security Model

### Trust Boundaries

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

**Data flow warning:** Tool responses flow directly into the LLM's context window and are sent to the LLM provider. Anything a tool returns — node IPs, hostnames, service configurations, kernel logs, file contents — becomes part of the prompt sent over the network. Do not use this server with clusters containing data you would not be comfortable sending to your LLM provider.

**Talos RBAC is server-side enforced.** The credentials in your talosconfig determine what operations are permitted on each node. talos-mcp cannot bypass Talos RBAC — a request that the API rejects will fail with an error, not silently succeed.

### Tool Classification and Minimum Required RBAC Role

| Tool | RBAC minimum |
|---|---|
| `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` |

### Safety Mechanisms

| Mechanism | How it works |
|---|---|
| Read-only mode | `TALOS_MCP_READ_ONLY=true` registers only read-only tools at startup; mutating tools are never exposed to the LLM |
| Path allowlist | `TALOS_MCP_ALLOWED_PATHS=/etc,/proc` restricts `talos_read_file` and `talos_list_files` to specified prefixes. **Defense-in-depth, not a hard boundary:** the check is local to the MCP server — symlinks on the remote Talos node that resolve outside an allowed prefix are not detected. |
| Confirm gates | Always require `confirm=true`: `talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`, `talos_reset`. Require `confirm=true` when `dry_run=false`: `talos_patch_config`, `talos_apply_config`. All enforced server-side. |
| Preserve default | `talos_upgrade` defaults `preserve` to `true` (keep EPHEMERAL partition) — differs from `talosctl` default of `false` |
| Dry-run default | `talos_patch_config` defaults to `dry_run=true`; applying requires both `dry_run=false` and `confirm=true` |
| Audit logging | All mutating tool calls (`talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`, `talos_reset`, `talos_patch_config`, `talos_apply_config`) emit a structured log line to stderr: `AUDIT timestamp= tool= nodes= args=` (patch content is redacted) |

### What Is Not in the Threat Model

- **The LLM itself** — prompt injection, hallucinated tool arguments, and LLM provider data retention are outside the scope of this server
- **The MCP client** — security of Claude Code, Codex, or other MCP clients is the responsibility of those projects
- **Network path between talos-mcp and Talos nodes** — protected by mutual TLS using the credentials in your talosconfig

### Least-Privilege Credential Setup

Create a dedicated talosconfig with minimal permissions for use with this server:

**Read-only access (recommended for most use cases):**

```bash
# Generate a reader-only talosconfig
talosctl config new --roles=os:reader talosconfig-readonly
```

Then set `TALOSCONFIG=/path/to/talosconfig-readonly` and `TALOS_MCP_READ_ONLY=true` for maximum restriction. With this setup, the server exposes only read-only tools and the credentials cannot perform any mutating operations even if a tool were somehow bypassed.

**Operator access (for service management, reboot, upgrade):**

```bash
talosctl config new --roles=os:operator talosconfig-operator
```

This covers all tools except `talos_patch_config` (which requires `os:admin`).

**Full access (required for config patching):**

Use your default talosconfig or generate one with `os:admin`. Reserve this for setups where config patch capability is explicitly needed.

## Verifying Downloads

### Checksums (integrity)

Each release includes a `talos-mcp__checksums.txt` file with SHA-256 hashes of all archives. Verify the binary after downloading:

```bash
# Download archive and checksums
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v/talos-mcp__linux_amd64.tar.gz
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v/talos-mcp__checksums.txt

# Verify
sha256sum --check --ignore-missing talos-mcp__checksums.txt
```

This detects corruption or truncated downloads. It does not protect against a compromised release pipeline.

### GitHub Artifact Attestations (SLSA L2 provenance)

Each release includes a GitHub-native build provenance attestation that cryptographically links the binary to the specific commit and workflow run that produced it:

```bash
gh attestation verify talos-mcp__linux_amd64.tar.gz \
  --repo Nosmoht/talos-mcp-server
```

This requires the [GitHub CLI](https://cli.github.com/). A passing verification means the artifact was produced by the official release workflow in this repository, not a third-party build.

### npm Package Provenance

The npm package is published with provenance attestation:

```bash
npm audit signatures
```

A passing result means the package was published by the official GitHub Actions release workflow via OIDC trusted publishing.

## Development

```bash
# 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 .
```

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Nosmoht](https://github.com/Nosmoht)
- **Source:** [Nosmoht/talos-mcp-server](https://github.com/Nosmoht/talos-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v2.3.1 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **2.3.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nosmoht-talos-mcp-server
- Seller: https://agentstack.voostack.com/s/nosmoht
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.