talos-mcp

library2.4.3jsnpmunverified

MCP server for Talos Linux cluster management via native gRPC API. Current stable version is 2.4.3, with active development and regular releases. Connects AI agents (Claude Code, OpenAI Codex, and any MCP-compatible client) to your Talos Linux cluster without requiring a Go toolchain—the correct native binary is installed automatically via npx. Tools return structured JSON directly from the Talos gRPC API, avoiding shell-scraping and reducing token cost. Reads ~/.talos/config by default, supporting read-only mode via TALOS_MCP_READ_ONLY env var. Requires Node >= 18.

devops

npm install talos-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TALOS-MCP

talos-mcp

devopsjavascriptv2.4.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default server start

✓ npx talos-mcp

✗ npm install -g talos-mcp && talos-mcp

npx is the recommended way to run; global install may cause version conflicts.

Client class

✓ import { TalosMcpClient } from 'talos-mcp'

✗ const { TalosMcpClient } = require('talos-mcp')

Package is ESM-only since v2.0; CommonJS require will fail with ERR_REQUIRE_ESM.

Type imports

✓ import type { Tool, Resource } from 'talos-mcp'

✗ import { Tool, Resource } from 'talos-mcp'

Use type-only imports for TypeScript type declarations to avoid runtime overhead.

Read-only mode configuration

✓ process.env.TALOS_MCP_READ_ONLY = 'true'

Set environment variable before starting the server; no import needed.

Shows how to start the talos-mcp server with npx, including read-only mode and custom config path.

// Ensure Node >= 18 // Run the MCP server (default reads ~/.talos/config) npx talos-mcp // For read-only mode: TALOS_MCP_READ_ONLY=true npx talos-mcp // Custom config path: TALOS_CONFIG=/path/to/talos/config npx talos-mcp // Example: list cluster members (requires MCP client) // In Claude Code: // /tool talos.list_members

Debug

Known issues

breakingPackage changed from CommonJS to ESM-only in v2.0.

fix

Use import syntax or dynamic import(). If you must use require(), pin to v1.x.

affects: >=2.0.0

breakingNode >= 18 required; older versions throw engine check error during npx.

fix

Upgrade Node to 18 or later. Check with 'node --version'.

affects: >=2.0.0

breakingThe talos-mcp binary is platform-specific; npx automatically downloads the correct one, but manual installation via npm install -g may fail on unsupported architectures.

fix

Always use npx talos-mcp instead of global install.

affects: all

gotchaTALOS_MCP_READ_ONLY=true only hides write tools but does not enforce server-side authorization; the underlying Talos API still enforces its own RBAC.

fix

Ensure Talos API users have appropriate RBAC roles; do not rely solely on this env var for security.

affects: all

deprecatedConfig file path fallback logic changed in v2.3; TALOS_CONFIG env var now takes precedence over ~/.talos/config.

fix

If you relied on the old behavior (always ~/.talos/config), set TALOS_CONFIG explicitly to that path.

affects: >=2.3.0

Errors

Common errors & fixes

Error: Cannot find module 'talos-mcp'

Using require() with ESM-only package after v2.0.

fix

Change to import { ... } from 'talos-mcp' or use dynamic import()

engine "node" is incompatible with this module. Expected version ">=18". Got "16.x.x"

Node version below 18 does not satisfy engine requirement.

fix

Upgrade Node to 18 or later: nvm install 18

Error: ENOENT: no such file or directory, open '~/.talos/config'

Talos config file not found or TALOS_CONFIG env var not set.

fix

Run 'talosctl config merge <path>' or set TALOS_CONFIG env var to the correct config file path.

Error: connect ECONNREFUSED <talos-api-endpoint>:50000

Talos API endpoint unreachable; cluster not running or network issue.

fix

Check cluster health: 'talosctl version'; ensure endpoint is accessible from your machine.

Upgrade

Version history

2.4.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/Nosmoht/talos-mcp-server ↗

packagetalos-mcp ↗

homepagehttps://github.com/Nosmoht/talos-mcp-server#readme ↗