Talos MCP server for Talos Linux

Talos オピニオン型 MCP サーバー

NOTE: このプロジェクトは現在活発に開発されています。

動機

最新のインフラでは、Terraform/OpenTofu、Ansible、GitOps などのツールがよく使われています。これらのツールは、Talos Linux のノードや Kubernetes クラスターをデプロイして設定します。

Talos MCP Server は、これらのツールに取って代わるものではありません。AI アシスタントや自動化エージェントが、Talos クラスターに関する情報にアクセスできるようにします。

デフォルトのツールは読み取り専用です。オプションのアクションツールは、--allow-destructive を指定すると有効になり、ノードを再起動できます。

ノードごとに多数の talosctl コマンドを実行する代わりに、AI アシスタントに必要な情報を収集して分析するよう依頼できます。インフラの変更を行う際は、引き続き既存の自動化ツールを主に使用します。

概要

このサーバーは、AI アシスタントなどの MCP クライアントを Talos API（apid）と、必要に応じて Talos ディスカバリーサービスに接続します。複数の Talos クラスターに対応し、構造化データを返します。

以下の用途に使用できます。

• クラスター、ノード、および Talos と Kubernetes のバージョンを確認する
• ノードの Talos サービスログとカーネルログ（dmesg）を読み取る
• 最近の Talos ランタイムイベントを確認する
• Talos API がダウンしている場合でも、ディスカバリーサービスからクラスターのメンバーを一覧表示する
• インフラの変更を行う前に情報を収集する

AI の手綱はしっかり握っておきましょう。

Talos ツール

MCP サーバーは以下のツールを提供します。

ツール	引数	説明
talos_clusters_list	なし	設定済みのクラスターを、エンドポイント、認証情報のロール、および各クラスターで使用可能なツールとともに一覧表示します。ネットワーク呼び出しは行いません。
talos_clusters_describe	cluster（省略可）	クラスター内のすべてのノードを、ロールおよび Talos と kubelet のバージョンとともに表示します。
talos_clusters_event	cluster、node、since、limit、actor_id（すべて省略可）	最近の Talos ランタイムイベントを、新しい順に一覧表示します。デフォルトは直近の 1h、イベント数は 50 件です。
talos_clusters_members	cluster、role（省略可）	ディスカバリーサービスから見たクラスターのメンバーを、ノード ID、ホスト名、ロール、アドレス、KubeSpan データとともに一覧表示します。ディスカバリーキーがあるクラスターでのみ使用できます。
talos_node_describe	cluster、node、logs、log_lines、events_since、event_limit（すべて省略可）	1 つのノードの詳細を表示します。バージョン、ステージと準備状況、リソース使用状況（CPU、負荷、メモリ、ディスク、上位プロセス）、すべてのサービスの状態とヘルス、最近のイベント、および不健全なサービスの直近のログ行が含まれます。出力内のシークレットはマスクされます。
talos_node_logs	service、cluster、node、kubernetes、tail、grep（service 以外は省略可）	Talos サービス（kubelet、etcd、apid、machined など）または Kubernetes コンテナーの直近のログ行を表示します。
talos_node_dmesg	cluster、node、tail、grep（すべて省略可）	ノードのカーネルログの直近の行を表示します。出力内のシークレットはマスクされます。

cluster は talosconfig のコンテキスト名です。省略すると、現在のコンテキストが使用されます。まず talos_clusters_list を使ってクラスター名を確認してください。MCP クライアントから、入力と出力のスキーマ全体を確認できます。コマンドラインからツールを一覧表示することもできます。

talos-mcp tools --talosconfig /absolute/path/to/talosconfig

--allow-destructive が有効で、クラスターの認証情報に os:operator ロールがある場合、talos_node_reboot は cluster、node、および省略可能な mode（default または powercycle）を受け付けます。Talos がリクエストを受け付けると応答し、ノードが復帰するまで待機することはありません。

各クラスターで使用できるツールは、クライアント証明書のロールによって異なります。os:reader では読み取り専用ツールを使用でき、os:operator ではさらに再起動ツールも使用できます。

インストール

Homebrew を使ってローカルにインストールするには、次を実行します。

brew install sergelogvinov/tap/talos-mcp

別のマシンでホストされている MCP サーバーを使用する場合、ローカルにインストールする必要はありません。

Talos クラスターを構成する

サーバーは、talosctl が使用するものと同じ標準の talosconfig を読み込みます。 各コンテキストは 1 つのクラスターです。必要な最小限の権限を持つ専用の認証情報を作成してください。

talosctl config new --roles os:reader --crt-ttl 8760h ~/.talos/mcp-config

コンテキストには、クラスター ID とシークレットを含むオプションの discovery ブロックを設定することもできます。これにより、talos_clusters_members が有効になります。

context: prod-eu
contexts:
  prod-eu:
    endpoints: [10.0.0.10, 10.0.0.11, 10.0.0.12]
    ca: LS0t...
    crt: LS0t...
    key: LS0t...
    discovery:
      cluster_id: 3x9y...
      cluster_secret: c2VjcmV0...

プライベートな key と cluster_secret は、パスフレーズ、age キー、または SSH キーを使って暗号化して保存できます。

talos-mcp config encrypt --talosconfig ~/.talos/mcp-config -o ~/.talos/mcp-config.enc \
    --recipient-file ~/.ssh/id_ed25519.pub
talos-mcp config check --talosconfig ~/.talos/mcp-config.enc \
    --talosconfig-identity ~/.ssh/id_ed25519

--talosconfig または TALOSCONFIG で talosconfig のパスを設定します。デフォルトは ~/.talos/config です。

すべての talosconfig フィールド、discovery ブロック、認証情報のロール、暗号化されたシークレットのロック解除オプション、 config import、encrypt、decrypt、check コマンド、デプロイの手順、トラブルシューティングについては、docs/config.md を参照してください。

MCP クライアントを構成する

ローカルの stdio サーバー

JSON MCP 構成を使用するクライアントの場合、次のようなエントリを追加します。

{
  "mcpServers": {
    "talos": {
      "command": "talos-mcp",
      "args": ["mcp"],
      "env": {
        "TALOSCONFIG": "/absolute/path/to/talosconfig"
      }
    }
  }
}

talosconfig に暗号化されたフィールドがある場合は、ロック解除元も設定します。たとえば、"TALOSCONFIG_IDENTITY": "/absolute/path/to/.ssh/id_ed25519" のように指定します。 mcp コマンドはパスフレーズの入力を求めません。

リモート HTTP サーバー

ストリーム可能な HTTP サーバーを次のように起動します。

talos-mcp server \
  --talosconfig /absolute/path/to/talosconfig \
  --listen-address :8080

MCP エンドポイントは http://host:8080/mcp で、ヘルスチェックは /healthz で提供されます。

リモートクライアントでは、末尾が /mcp の HTTPS URL を使用します。

{
  "mcpServers": {
    "talos": {
      "type": "http",
      "url": "https://talos-mcp.example.com/mcp"
    }
  }
}

サーバーは HTTP エンドポイントに対するユーザー認証を提供しません。すべての呼び出し元がサーバーの talosconfig にある認証情報を使用するため、ネットワークポリシーまたは認証プロキシでエンドポイントを保護してください。

Kubernetes 用の Helm チャートは charts/talos-mcp で利用できます。

構成を保存した後、MCP クライアントを再起動するか、再読み込みしてください。

実行

共通フラグ

mcp、server、tools コマンドでは、次のフラグを使用します。各フラグは環境変数でも設定できます。コマンドラインフラグは環境変数より優先されます。

フラグ	環境変数	デフォルト	説明
--talosconfig <path>	TALOSCONFIG	~/.talos/config	talosconfig ファイルのパスです。
--context <name>	TALOS_CONTEXT	すべてのコンテキスト	この talosconfig コンテキストのみを使用します。
--talosconfig-identity <path>	TALOSCONFIG_IDENTITY	なし	暗号化されたフィールドを復号する age アイデンティティまたは OpenSSH 秘密鍵です。複数回指定できます。
--talosconfig-passphrase-file <path>	TALOSCONFIG_PASSPHRASE_FILE	なし	暗号化されたフィールドのパスフレーズが記載されたファイルです。
--talosconfig-askpass <program>	TALOSCONFIG_ASKPASS	なし	暗号化されたフィールドのパスフレーズを出力するプログラムです。
--extensions <list>	EXTENSIONS	all	有効にするツールグループをカンマ区切りで指定します。cluster、node、または all を指定できます。
--allow-destructive	ALLOW_DESTRUCTIVE	false	talos_node_reboot などの破壊的なツールを許可します。
--log-level <level>	LOG_LEVEL	info	ログレベルです。debug、info、warn、または error を指定できます。
--log-format <format>	LOG_FORMAT	text	ログ出力形式です。text または json を指定できます。

server コマンドでは、--listen-address（LISTEN_ADDRESS、デフォルトは 127.0.0.1:8080）と --require-all-contexts （REQUIRE_ALL_CONTEXTS）も指定できます。コンテナーイメージでは LISTEN_ADDRESS=:8080 が設定されています。tools コマンドでは、text、json、または yaml を指定する --output（-o）を使用できます。デフォルトは text です。

たとえば、JSON ログを有効にして stdio サーバーを実行するには、次のようにします。

talos-mcp mcp \
  --talosconfig /absolute/path/to/talosconfig \
  --log-format json

構成をテストする

talosconfig とその暗号化されたフィールドを確認します。

talos-mcp config check --talosconfig /absolute/path/to/talosconfig

利用可能なすべてのツールを一覧表示します。

export TALOSCONFIG="/absolute/path/to/talosconfig"
talos-mcp tools

ツールを直接呼び出します。

talos-mcp tools talos_clusters_list
talos-mcp tools talos_clusters_describe cluster=prod-eu
talos-mcp tools -o json talos_node_logs cluster=prod-eu node=10.0.0.10 service=kubelet tail=50

ライセンス

Apache License, Version 2.0（以下「本ライセンス」といいます）の下でライセンスされています。 本ライセンスに従わない限り、このファイルを使用することはできません。 本ライセンスのコピーは、以下から入手できます。

http://www.apache.org/licenses/LICENSE-2.0

適用される法律で要求される場合、または書面で合意されている場合を除き、本ライセンスに基づいて配布されるソフトウェアは、「現状有姿」で提供され、明示的か黙示的かを問わず、いかなる保証や条件もありません。 本ライセンスに基づく許可および制限については、本ライセンスの本文をご確認ください。

---

Talos LinuxはSidero Labs, Inc.の商標です。