Talos Linux MCP Server

talos-mcp

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

npx talos-mcp

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

npm install -g talos-mcp

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

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:

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 for the mechanism.

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

Download the latest release from GitHub Releases, extract, and place the binary in your $PATH.

Build from source (requires Go 1.21+):

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:

Compatibility

This server is tested against Talos Linux v1.9.x through v1.13.x.

The server logs a startup warning if the connected cluster's Talos version is outside the tested range. All 19 gRPC methods used have been stable since Talos v1.9.

Upgrade path validation

The talos_upgrade tool validates that the target version follows Talos's supported upgrade path — at most one minor version at a time (e.g. v1.11.x → v1.12.x). Upgrades that skip minor versions are rejected with an error.

If your image uses a custom or factory tag (e.g. factory.talos.dev/... or :latest) the tag cannot be parsed and validation is skipped automatically. To bypass validation explicitly, set TALOS_MCP_SKIP_VERSION_CHECK=true.

Client Setup

Claude Code

Add to your project's .mcp.json:

{

"mcpServers": { "talos": { "command": "npx", "args": ["-y", "talos-mcp"] } } }

Or globally in ~/.claude.json under "mcpServers". If you prefer a local binary, replace "command": "npx" with the path to the binary.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "talos": { "command": "npx", "args": ["-y", "talos-mcp"] } } }

OpenAI Codex

Add to .codex/config.toml (project) or ~/.codex/config.toml (global):

[mcp_servers.talos]

command = "npx" args = ["-y", "talos-mcp"]

[mcp_servers.talos.env] TALOSCONFIG = "/path/to/talosconfig"

Generic MCP client

The server speaks the MCP protocol over stdio:

./talos-mcp

Tools

Read-only

Mutating

These tools modify cluster state and have explicit safety guards.

All tools accept an optional nodes field (list of node IPs or hostnames). When omitted, the active context from talosconfig is used.

Maintenance-mode (--insecure) operations

talos_apply_config, talos_get, talos_version, and talos_meta accept an insecure=true flag that targets a node in maintenance mode (booted but not yet configured). The transport is TLS-encrypted but bypasses mTLS — there is no client certificate and (by default) no server-certificate verification. This is required for bootstrapping fresh nodes (talosctl apply-config --insecure equivalent).

• Operator opt-in required. Set TALOS_MCP_ENABLE_INSECURE=true (or use the expert safety profile). Without it, every insecure=true call is refused.
• Endpoint allowlist required. Set TALOS_MCP_INSECURE_ALLOWED_NODES to a comma-separated list of permitted maintenance-mode IPs / CIDRs. The startup is aborted if it is missing or contains 0.0.0.0/0, ::/0, an IPv4 mask <16, or an IPv6 mask <48. Use /28 or narrower in production.
• Endpoint must be a bare IP. No hostnames, no host:port, no scheme, no IPv6 zone. Link-local (incl. 169.254.169.254 IMDS), loopback, multicast, and unspecified addresses are rejected.
• MITM mitigation via TOFU pinning. Pass cert_fingerprint=<64-hex> (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

| diagnose-node | Guided diagnosis workflow