Talos Linux Mcp Server

talos-mcp

Talos Linux クラスターの管理機能を AI エージェント（Claude Code、OpenAI Codex、および MCP 互換クライアント）に提供する MCP サーバーです。talosctl の出力をチャットに貼り付ける代わりに、エージェントが構造化ツールを呼び出し、Talos gRPC API から機械可読な JSON を直接取得します。中間出力にトークンコストはかかりません。

talosctl と同じ mTLS 認証情報（~/.talos/config）を使用し、ネイティブの Talos gRPC API 経由でクラスターに接続します。

インストール

npm 経由（Go は不要、Linux/macOS、amd64/arm64）：

npx talos-mcp

$PATH から継続的に呼び出す場合は、**npm（グローバルインストール）**を使用します：

npm install -g talos-mcp

バイナリは <npm-prefix>/bin/talos-mcp にインストールされます。次のコマンドで確認できます：

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

公開済みの最新リリースにアップグレードします：

npm install -g talos-mcp@latest

main への feat: / fix: / perf:（または破壊的変更を含む）マージのたびに、新しいリリースが数分以内に npmjs.com に公開されます。仕組みについては、CONTRIBUTING.md § マージ後のリリースパイプラインをご覧ください。

バイナリをダウンロード（Linux/macOS、amd64/arm64）：

GitHub Releasesから最新リリースをダウンロードして展開し、バイナリを $PATH に配置します。

ソースからビルド（Go 1.21 以降が必要）：

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

設定

デフォルトでは ~/.talos/config（talosctl が使用するものと同じファイル）を読み込みます。環境変数で上書きできます。

変数	デフォルト	説明
TALOSCONFIG	~/.talos/config	talosconfig ファイルへのパス
TALOS_CONTEXT	active context	使用するコンテキスト名
TALOS_ENDPOINTS	from config	エンドポイントのカンマ区切りの上書き値
TALOS_MCP_READ_ONLY	false	true に設定すると、起動時にすべての変更を伴うツールを無効にします
TALOS_MCP_HTTP_ADDR	(unset)	設定すると（例：:8080）、stdio の代わりに Streamable HTTP を提供します
TALOS_MCP_AUTH_TOKEN	(unset)	HTTP モードが有効な場合に必要なベアラートークン
TALOS_MCP_ALLOWED_NODES	(unset)	ツールの対象として許可する IP、ホスト名、CIDR 範囲のカンマ区切りリスト。未設定の場合はすべて許可します。
TALOS_MCP_ALLOWED_PATHS	(all)	talos_read_file および talos_list_files で許可するパスのプレフィックス（例：/etc,/proc）のカンマ区切りリスト。多層防御のみを目的としたものです。チェックは MCP サーバーのホスト上で実行され、リモートの Talos ノード上のシンボリックリンクは解決されないため、許可されたプレフィックス下にある別の場所を指すシンボリックリンクは検出されません。
TALOS_MCP_SKIP_VERSION_CHECK	false	true に設定すると、アップグレードパスの検証を省略します（例：ファクトリーイメージやカスタムタグの場合）
TALOS_MCP_ENABLE_INSECURE	false	talos_apply_config / talos_get / talos_version / talos_meta で insecure=true を有効にします。mTLS をバイパスします — TALOS_MCP_INSECURE_ALLOWED_NODES が必須です。
TALOS_MCP_INSECURE_ALLOWED_NODES	(unset)	メンテナンスモードのエンドポイントとして許可する IP / CIDR のカンマ区切りリスト。TALOS_MCP_ENABLE_INSECURE=true の場合に必須です。拒否される値：0.0.0.0/0、::/0、IPv4 マスク <16、IPv6 マスク <48。
TALOS_MCP_META_PRIVILEGED_KEYS	(none)	UserReserved1/2/3 以外に、talos_meta による書き込み／削除を許可する META キー（10 進数または 0x 接頭辞付きの 16 進数）のカンマ区切りリスト。
TALOS_MCP_SAFETY_PROFILE	(unset)	ゲーティングフラグの初期値を設定するプリセット：conservative / standard / expert。expert は EnableInsecure を有効にします。
TALOS_MCP_RATE_LIMIT	10	HTTP モード：トークンバケットの補充レート（リクエスト／秒、浮動小数点数）
TALOS_MCP_RATE_BURST	20	HTTP モード：トークンバケットのバースト容量（整数）
TALOS_MCP_MAX_BODY_SIZE	4194304	HTTP モード：POST リクエスト本文の最大サイズ（バイト、デフォルトは 4 MiB）
TALOS_MCP_MAX_CONCURRENT	20	HTTP モード：同時に処理できる POST ハンドラーの最大数（過負荷時は即時に 503 を返します）
TALOS_MCP_SUBSCRIPTION_RATE	1s	(session, URI) の組ごとに配信する resources/updated 通知の最小間隔（Go の duration。例：500ms）
TALOS_MCP_SUBSCRIPTION_BURST	3	レート制限が適用されるまでに、(session, URI) の組ごとに送信する初回通知のバースト数

互換性

このサーバーは Talos Linux v1.9.x から v1.13.x に対してテストされています。

talos-mcp	Talos Linux	machinery SDK
v0.x (current)	v1.9.0 – v1.13.x	v1.13.4

接続されたクラスターの Talos バージョンがテスト済みの範囲外の場合、サーバーは起動時に警告をログに記録します。使用される 19 個の gRPC メソッドはすべて、Talos v1.9 以降安定しています。

アップグレードパスの検証

talos_upgrade ツールは、対象バージョンが Talos のサポート対象アップグレードパスに沿っていることを検証します。1 回に進められるのはマイナーバージョン 1 つまでです（例：v1.11.x → v1.12.x）。マイナーバージョンを飛ばすアップグレードはエラーで拒否されます。

イメージでカスタムタグまたはファクトリータグ（例：factory.talos.dev/... や :latest）を使用している場合、タグを解析できないため、検証は自動的に省略されます。明示的に検証を省略するには、TALOS_MCP_SKIP_VERSION_CHECK=true を設定してください。

クライアントのセットアップ

Claude Code

プロジェクトの .mcp.json に追加します。

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

または、~/.claude.json の "mcpServers" の下にグローバル設定として追加します。ローカルバイナリを使用する場合は、"command": "npx" をバイナリへのパスに置き換えてください。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

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

OpenAI Codex

.codex/config.toml（プロジェクト）または ~/.codex/config.toml（グローバル）に追加します。

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

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

汎用 MCP クライアント

サーバーは stdio 経由で MCP protocol を使用します。

./talos-mcp

ツール

読み取り専用

ツール	説明
talos_resource_definitions	利用可能なすべてのリソースタイプとそのエイリアスを一覧表示します。照会可能な内容を確認するため、最初に呼び出してください。
talos_get	タイプ（例：MachineStatus、Member、NodeAddress、Service）を指定して、任意の COSI リソースを取得または一覧表示します。メンテナンスモード（insecure=true + endpoint）に対応しています。
talos_version	対象ノードから Talos のバージョン情報を取得します。メンテナンスモード（insecure=true + endpoint）に対応しています。
talos_services	すべての Talos サービスと現在の状態（実行中、停止、ヘルス）を一覧表示します。
talos_containers	名前空間内のコンテナーを一覧表示します（Kubernetes コンテナーのデフォルトは k8s.io）。
talos_processes	対象ノードで実行中のプロセスを一覧表示します。
talos_health	クラスターのヘルス（etcd、Kubernetes API、ノードの準備状況）を確認します。control_plane_nodes / worker_nodes によるオーバーライドに対応しています。
talos_logs	サービスの最近のログを取得します（末尾 N 行、追跡なし）。
talos_dmesg	カーネルリングバッファーのメッセージを読み取ります。
talos_events	最近の Talos ランタイムイベント（サービスの変更、設定の変更）を取得します。
talos_etcd	etcd クラスターを照会します：members（デフォルト）または status。
talos_etcd_snapshot	etcd スナップショットをローカルのファイルパスにストリーミングします。
talos_list_files	ノードのファイルシステム上のファイルとディレクトリを一覧表示します。
talos_read_file	ノードのファイルシステムからファイルの内容を読み取ります。
talos_validate	クラスターに接続せずに、マシン設定（YAML/JSON）をオフラインで検証します。

変更を伴う操作

これらのツールはクラスターの状態を変更するため、明示的な安全ガードが設けられています。

ツール	説明	ガード
talos_service_action	Talos サービスを起動、停止、または再起動します（注：etcd の再起動は Talos API でサポートされていません）。	confirm=true が必要
talos_reboot	対象ノードを再起動します。mode：default、powercycle、force に対応しています。	confirm=true が必要。nodes を明示的に指定する必要があります
talos_upgrade	対象ノードの Talos をアップグレードします。preserve（デフォルトは true）、stage、force、reboot_mode に対応しています。	confirm=true が必要。nodes と image が必要です
talos_rollback	対象ノードで最後のアップグレードをロールバックします。	confirm=true が必要。nodes を明示的に指定する必要があります
talos_patch_config	対象を絞ったマシン設定パッチ（strategic-merge または RFC 6902 JSON Patch）を適用します。	dry_run のデフォルトは true です。dry_run=false の場合は confirm=true が必要です
talos_reset	対象ノードを消去して工場出荷時の状態にリセットします（元に戻せません）。	confirm=true が必要。nodes を明示的に指定する必要があります
talos_apply_config	単一ノードに完全なマシン設定を適用します。新規ノードのブートストラップ用に、メンテナンスモード（insecure=true + endpoint）に対応しています。	dry_run のデフォルトは true です。dry_run=false の場合は confirm=true が必要です
talos_meta	META パーティションのキーと値のペアを読み取り、書き込み、または削除します。メンテナンスモード（insecure=true + endpoint）に対応しています。	write / delete には confirm=true が必要です。UserReserved* 以外のキーには、TALOS_MCP_META_PRIVILEGED_KEYS への列挙が必要です

すべてのツールは、オプションの nodes フィールド（ノードの IP アドレスまたはホスト名のリスト）を受け取ります。省略した場合は、talosconfig のアクティブなコンテキストが使用されます。

メンテナンスモード（--insecure）での操作

talos_apply_config、talos_get、talos_version、talos_meta は、メンテナンスモード（起動済みで、まだ設定されていない状態）のノードを対象とする insecure=true フラグを受け付けます。トランスポートは TLS で暗号化されますが、mTLS はバイパスされます。クライアント証明書は不要で、デフォルトではサーバー証明書も検証されません。これは、新しいノードをブートストラップするために必要です（talosctl apply-config --insecure と同等です）。

• オペレーターによる明示的な許可が必要です。 TALOS_MCP_ENABLE_INSECURE=true を設定するか、expert セーフティプロファイルを使用してください。設定しない場合、insecure=true を指定したすべての呼び出しは拒否されます。
• エンドポイントの許可リストが必要です。 メンテナンスモードで許可する IP アドレス／CIDR をカンマ区切りで TALOS_MCP_INSECURE_ALLOWED_NODES に設定してください。設定されていない場合、または 0.0.0.0/0、::/0、IPv4 のマスク <16、IPv6 のマスク <48 が含まれている場合、起動は中止されます。本番環境では /28 以下の範囲を使用してください。
• エンドポイントは IP アドレスのみを指定してください。 ホスト名、host:port、スキーム、IPv6 ゾーンは使用できません。リンクローカル（169.254.169.254 IMDS を含む）、ループバック、マルチキャスト、未指定のアドレスは拒否されます。
• TOFU ピン留めによって MITM を軽減します。 cert_fingerprint=<64-hex>（Talos コンソールのバナーからコピーしたサーバーの SHA-256 フィンガープリント）を渡すと、リーフ証明書の検証が有効になります。指定しない場合、MCP サーバーと対象ノード間の経路上にいる誰もが MITM 攻撃を行えます。
• META の書き込み／削除の許可リスト。 talos_meta の書き込み／削除は meta.UserReserved1／2／3 に制限されます。特権キー（Upgrade、StateEncryptionConfig、…）は、一括指定ではなく、キーごとに TALOS_MCP_META_PRIVILEGED_KEYS で列挙する必要があります。

プロンプト

プロンプト	説明
diagnose-node	1 台のノードを対象とした、ガイド付きの診断ワークフローです。
investigate-etcd	etcd クラスターの異常を重点的に調査します。
debug-service	サービス固有の診断ワークフローです（kubelet、containerd、etcd、…）。
pre-upgrade-checklist	Talos のアップグレード前に行う事前確認です。
apply-config	マシン設定パッチを適用するためのガイド付きフローです（TALOS_MCP_READ_ONLY が未設定の場合にのみ登録されます）。

リソースとサブスクリプション

サーバーは Talos COSI リソースを MCP リソースとして公開します。

• talos://cluster/version — クラスターの静的なバージョン情報です。
• talos://cluster/resource-definitions — リソースの種類を確認します。
• talos://{node}/resource/{namespace}/{type}[/{id}] — 特定のノード上の COSI リソースを一覧表示または取得します。

resources/subscribe を実装する MCP クライアント（Claude Desktop、Cursor）は、基盤となるリソースが変更されるたびに notifications/resources/updated を受信します。ポーリングは不要です。サブスクリプションは Talos COSI の Watch／WatchKindAggregated ストリームを利用し、読み取りと同じ TALOS_MCP_ALLOWED_NODES 許可リストに従います。

サブスクリプション可能なリソースの種類（正式名称）：

• MachineStatuses.runtime.talos.dev（MachineStatus）
• Members.cluster.talos.dev（Member）
• NodeAddresses.net.talos.dev（NodeAddress）
• Services.v1alpha1.talos.dev（Service）

許可リストの確認前にエイリアスは正式な種類に解決されるため、talos://{node}/resource/runtime/ms/...（MachineStatus のエイリアス）を購読するクライアントも成功します。その他の COSI の種類は resource type %q is not subscribable で拒否されます。静的な talos://cluster/* URI はサブスクリプションできません（COSI による基盤がありません）。

配信は TALOS_MCP_SUBSCRIPTION_RATE／TALOS_MCP_SUBSCRIPTION_BURST によって (session, URI) ごとにレート制限されます。制限を超えたイベントは破棄され、追いつくためにクライアントはリソースを再読み込みします。初期の Bootstrapped イベントは意図的に転送されません。クライアントは初期状態を取得するため、購読後に一度 resources/read を呼び出すことが想定されています。

セキュリティモデル

信頼境界

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

データフローに関する警告： ツールの応答は LLM のコンテキストウィンドウに直接流れ込み、LLM プロバイダーに送信されます。ツールが返すすべての情報（ノードの IP アドレス、ホスト名、サービス構成、カーネルログ、ファイルの内容など）は、ネットワーク経由で送信されるプロンプトの一部になります。LLM プロバイダーに送信することに抵抗があるデータを含むクラスターでは、このサーバーを使用しないでください。

Talos RBAC はサーバー側で適用されます。 talosconfig の認証情報によって、各ノードで許可される操作が決まります。talos-mcp が Talos RBAC を回避することはできません。API が拒否したリクエストは、黙って成功するのではなく、エラーになります。

ツールの分類と必要最小限の RBAC ロール

ツール	RBAC の最小要件
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

安全機構

機構	動作
読み取り専用モード	TALOS_MCP_READ_ONLY=true を設定すると、起動時に読み取り専用ツールのみが登録されます。変更を行うツールが LLM に公開されることはありません
パスの許可リスト	TALOS_MCP_ALLOWED_PATHS=/etc,/proc を設定すると、talos_read_file と talos_list_files の対象を指定したプレフィックスに制限できます。**多層防御の一環であり、完全な境界ではありません。**リモートの Talos ノード上にあるシンボリックリンクが許可されたプレフィックスの外を指していても、MCP サーバー側で行われるこのチェックでは検出されません。
確認ゲート	talos_service_action、talos_reboot、talos_upgrade、talos_rollback、talos_reset では、常に confirm=true が必要です。talos_patch_config と talos_apply_config では、dry_run=false の場合に confirm=true が必要です。いずれもサーバー側で適用されます。
デフォルト値の保持	talos_upgrade では preserve のデフォルト値が true（EPHEMERAL パーティションを保持）です。これは talosctl のデフォルト値 false とは異なります
ドライランのデフォルト	talos_patch_config の dry_run のデフォルト値は true です。適用するには、dry_run=false と confirm=true の両方が必要です
監査ログ	変更を行うすべてのツール呼び出し（talos_service_action、talos_reboot、talos_upgrade、talos_rollback、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 を作成します。

読み取り専用アクセス（ほとんどの用途で推奨）：

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

次に、最大限の制限を適用するため、TALOSCONFIG=/path/to/talosconfig-readonly と TALOS_MCP_READ_ONLY=true を設定します。この構成では、サーバーが公開するのは読み取り専用ツールのみであり、仮にツールが何らかの方法で回避された場合でも、認証情報によって変更操作を実行することはできません。

オペレーターアクセス（サービス管理、再起動、アップグレード用）：

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

これで、os:admin が必要な talos_patch_config を除くすべてのツールを利用できます。

フルアクセス（設定のパッチ適用に必要）：

デフォルトの talosconfig を使用するか、os:admin を持つものを生成してください。この権限は、設定にパッチを適用する機能が明示的に必要な構成に限って使用してください。

ダウンロードの検証

チェックサム（完全性）

各リリースには、すべてのアーカイブの SHA-256 ハッシュを記載した talos-mcp_<version>_checksums.txt ファイルが含まれています。ダウンロード後にバイナリを検証してください。

# Download archive and checksums
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

# Verify
sha256sum --check --ignore-missing talos-mcp_<version>_checksums.txt

これにより、破損やダウンロードの中断を検出できます。リリースパイプラインが侵害されている場合は保護できません。

GitHub Artifact Attestations（SLSA L2 の来歴）

各リリースには、バイナリを生成した特定のコミットとワークフロー実行に暗号学的に結び付ける、GitHub ネイティブのビルド来歴アテステーションが含まれています。

gh attestation verify talos-mcp_<version>_linux_amd64.tar.gz \
  --repo Nosmoht/talos-mcp-server

これには GitHub CLI が必要です。検証に成功した場合、そのアーティファクトがサードパーティーのビルドではなく、このリポジトリの公式リリースワークフローによって生成されたことを意味します。

npm パッケージの来歴

npm パッケージは、来歴アテステーション付きで公開されます。

npm audit signatures

検証に成功した場合、そのパッケージが OIDC の信頼された公開を通じて、公式の GitHub Actions リリースワークフローによって公開されたことを意味します。

開発

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

ライセンス

MIT