rancher-mcp

あらゆる MCP クライアントから Rancher 管理下の Kubernetes を操作できます — 検出、汎用リソースアクセス、厳選されたオペレーター向けワークフローを、 監査ログ、レート制限、確認による保護を備えた安全モデルで実現します。

クイックスタート · ツールの概要 · アーキテクチャ · 安全モデル · 互換性 · 開発

---

これが必要な理由

Rancher は実際の Kubernetes フリートを運用するためのものであり、2 つの API（レガシー Norman /v3 プレーンとモダンな Steve /v1 プレーン）を提供します。バージョンによって動作が異なり、 各クラスターはそれぞれ独自のプロキシの背後にあります。汎用 Kubernetes MCP サーバーを接続しても Rancher 固有の機能はすべて見落とされます。一方、エージェントから生の kubectl を使うと、 監査可能性、ガードレール、管理プレーンの全体像を失います。

MCP Rancher は、こうした現実に対応するために構築されています。

• バージョンを前提にせず、機能を認識します。 接続された各 Rancher が実際にサポートする機能を検出し、 決めつけません。1 つのバイナリで、同じツール群を使って 2.6.5 → 2.9.3 に対応します。
• マルチインスタンスを最優先します。 ラボ、ステージング、本番環境をすべて設定できます。本番環境に read_only: true を指定すると、ガードが作動する前に、設定レイヤーですべての変更操作が拒否されます。
• アクセスできないものはありません。 厳選されたツールで一般的なケースの 95% をカバーし、汎用 エンジンによって、どちらの API プレーンが公開するリソースにもアクセスできます。まだツールが 用意されていない種類にも対応します。

ツールの構成

206 個のツール：読み取り専用 178 個・書き込み 28 個・破壊的操作 5 個 — 手作業ではなく、レジストリ自体から集計しています。docs/tool-manifest.json は 実行中の FastMCP レジストリから生成（make tool-manifest）され、コードとの不一致があれば CI のゲートがビルドを失敗させます。ツールごとの説明、安全性の注釈、パラメーターはすべてここに記載されています。スライスの追跡機能を備えた説明用レジストリは docs/tool-catalog.md です。

レイヤー	機能	例
検出とスキーマ	任意のインスタンスで可能な操作を調べます	rancher_server_version、rancher_norman_schema_list、rancher_capability_domain_list
汎用エンジン	両プレーンにおけるあらゆるリソースの CRUD、アクション、リンク、監視	rancher_steve_resource_list、rancher_norman_resource_action_invoke、rancher_steve_resource_watch
厳選された読み取り	約 25 のドメインにわたる、型付け済みで整形されたレスポンス	rancher_pods_list、rancher_deployments_list、rancher_longhorn_volumes_list、rancher_policy_reports_list
厳選された書き込み	ガード付きの変更操作	rancher_deployment_scale、rancher_deployment_restart、rancher_cron_job_suspend、rancher_node_cordon、rancher_secret_create
オペレーター向け集約	1 回の呼び出しでトリアージ	rancher_cluster_health_check、rancher_find_failing_pods、rancher_find_stalled_rollouts、rancher_project_health_summary

対象ドメイン：クラスターとノード · プロジェクトと名前空間 · ワークロード · ポッドとサービス · ストレージ · ネットワーク · 設定とシークレット (値はマスクされます) · 証明書 (鍵はマスクされます) · RBAC · 認証と ID · アプリとカタログ · ロギングパイプライン · Prometheus モニタリング · ポリシーレポート · CIS コンプライアンス · バックアップオペレーター · etcd バックアップ · Longhorn · Fleet · プロビジョニング · 設定と機能 · アラートと通知先。

206 個すべてをデフォルトで公開しています。各ツールのスキーマは Claude Code 独自の検索機能によって遅延読み込みされるため、デフォルトの数を減らしても、優れたホストを犠牲にして他のホストに利点をもたらすだけです。制約のあるホスト（小規模なローカルモデルや厳しいコンテキスト予算を持つホスト）では、RANCHER_TOOLSETS を使って公開するツールを絞れます。Configuration のツールセットプロファイルを参照してください。

クイックスタート

要件

• Python 3.12 以降と uv
• Rancher API トークン（作成方法）

インストールと実行

# From source
git clone https://github.com/rex/mcp-rancher.git
cd mcp-rancher
make setup                 # deps, .env scaffold, pre-commit hooks
cp .env.example .env       # set RANCHER_URL + RANCHER_TOKEN
make dev                   # run the MCP server (stdio)

PyPI への公開後は、uvx rancher-mcp の 1 行で実行できます。

Claude Code

claude mcp add rancher \
  -e RANCHER_URL=https://rancher.example.com \
  -e RANCHER_TOKEN=token-xxxxx:yyyyyyyyy \
  -- uv run --directory /path/to/mcp-rancher rancher-mcp

Claude Desktop

{
  "mcpServers": {
    "rancher": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-rancher", "rancher-mcp"],
      "env": {
        "RANCHER_URL": "https://rancher.example.com",
        "RANCHER_TOKEN": "token-xxxxx:yyyyyyyyy"
      }
    }
  }
}

複数のインスタンス

RANCHER_INSTANCES_JSON='{
  "production": {"url": "https://rancher.prod.example.com",    "token": "token-a:xxx", "verify_ssl": true, "read_only": true},
  "lab":        {"url": "https://rancher.lab.example.com",     "token": "token-b:yyy", "verify_ssl": false, "read_only": false}
}'
RANCHER_DEFAULT_INSTANCE=production

すべてのツールは省略可能な instance 引数を受け取ります。read_only: true が設定されたインスタンスは、設定レイヤーですべての変更操作を拒否します。

アーキテクチャ

flowchart LR
    A[MCP client<br/>Claude Code · Claude Desktop · any] -- stdio --> S

    subgraph S[rancher-mcp]
        direction TB
        L1[Discovery & schema<br/>planes · schemas · capabilities]
        L2[Generic engine<br/>any resource · both planes<br/>CRUD · actions · links · watch]
        L3[Curated tools<br/>typed models · shaped output<br/>next-step hints]
        G[Safety layer<br/>read-only guard · confirmation phrases<br/>audit log · rate limit · masking]
        L1 --> L2 --> L3
        L3 --> G
        L2 --> G
    end

    G -- Norman /v3 --> R1[(Rancher<br/>instance A)]
    G -- Steve /v1 + k8s proxy --> R1
    G -- Norman + Steve --> R2[(Rancher<br/>instance B)]

意図的に分離された 3 つのレイヤーがあります。検出ではインスタンスで可能な操作がわかり、汎用エンジンでは公開されているあらゆる機能を操作でき、厳選されたツールではよく使われる操作を型付けし、整形して、自己記述的にします（すべてのレスポンスに suggested_next_steps が含まれます）。厳選されたツールの大半は、ドリフト検出ゲートを備え、YAML ディスクリプター（catalog/curated_tools/）から生成されます。編集上の判断はボイラープレートではなく、ディスクリプターに記載されています。

安全モデル

エージェントが、あなたの給与を支払うクラスターを操作する日を想定して設計されています。

ガード	動作
読み取り専用インスタンス	read_only: true の場合、そのインスタンスに対するすべての変更操作を、ツールのロジックが実行される前に拒否します
破壊的操作の確認	削除には明示的に入力したフレーズ（例："delete steve namespace foo"）が必要です。フレーズがなければ削除できません
ツールのアノテーション	すべてのツールが readOnlyHint／destructiveHint／idempotentHint を宣言するため、クライアントはこれらに基づいて UX を制御できます
監査ログ	すべての変更操作で、構造化された event="audit" レコード（ツール、操作、プレーン、インスタンス、リソース、結果）を出力します。記録するのは引数の名前のみで、値は記録しません
レート制限	書き込み操作にはトークンバケット方式を適用します（デフォルトは毎分60回）。暴走したループが API に大量のリクエストを送り続けることを防ぎます
シークレットと鍵のマスキング	キュレーション済みのレスポンスには、シークレットの値と証明書の秘密鍵は構造上含まれません（表示には汎用ツールで明示的なオプトインが必要です）
構造化エラー	ガードによる拒否は、エージェントが条件分岐に使える型付きの error_code エンベロープを返します。未加工の文字列は返しません

互換性

主な対象	Rancher 2.9.3（本番環境で検証済み）
互換性の下限	Rancher 2.6.5（機能検出によって互換性を維持）
API プレーン	Norman /v3 + Steve /v1（およびクラスターごとの Kubernetes プロキシ）
トランスポート	stdio

機能検出により実行時にバージョン間の差異を吸収するため、バージョンに固定したビルドや「自分の Rancher では動く」といった事態はありません。両方の対象バージョンを同じテストスイートで検証しており、読み取りパスは 2.6.5 のラボ環境と 2.9.3 の本番環境の両方に対して実環境で検証済みです （検証レポート）。

設定

変数	デフォルト	用途
RANCHER_URL	—	Rancher サーバーの URL（単一インスタンスモード）
RANCHER_TOKEN	—	API トークン（token-xxxxx:yyyyyyyyy）
RANCHER_VERIFY_SSL	true	TLS 検証
RANCHER_INSTANCES_JSON	—	複数インスタンスの設定（上記を参照）
RANCHER_DEFAULT_INSTANCE	最初に定義されたインスタンス	ツール呼び出しでインスタンスが指定されていない場合に使用するインスタンス
RANCHER_MCP_SERVER_NAME	rancher-mcp	クライアントに通知するサーバーの識別名
RANCHER_MCP_SERVER_DESCRIPTION	組み込み	クライアントに通知するサーバーの説明
RANCHER_MCP_WRITE_RATE_LIMIT_PER_MIN	60	書き込みのレート制限（0 で無効）
RANCHER_TOOLSETS	all	起動時に公開する、カンマ区切りのツールセットプロファイル（下記を参照）
RANCHER_TOOLS	—	選択したプロファイルに追加して、必ず含めるツール名をカンマ区切りで指定
RANCHER_EXCLUDE_TOOLS	—	除外するツール名をカンマ区切りで指定。最後に適用され、常に RANCHER_TOOLS より優先されます

ツールセットプロファイル

デフォルトはallで、すべてのツールが公開されます。主要なホストであるClaude Codeは、すべてのツールスキーマを独自の検索機能の背後に置くため、デフォルトを小さくしても他のホストには役立ちますが、優れたホストの利便性を損なうだけです。これは意図的な選択であり、見落としではありません。

RANCHER_TOOLSETSを使うと、制約のあるホスト（小規模なローカルモデルやコンテキスト予算が限られている場合）で、公開するツールを絞り込めます。値には、src/rancher_mcp/tools/内のモジュールごとに1つのファミリー名（storage、workloads、pods_services、rbacなど。全リストはrancher_mcp.toolsets.FAMILY_REGISTRARSを参照）か、ファミリーをまたぐcoreプロファイルを指定できます。coreは、トリアージ／状況把握に使う約32個のツールセットです（rancher_find_*、ヘルス／サマリーの集計ツール、基本的なlist/getの組み合わせ、汎用のrancher_{steve,norman}_resource_{list,get}という代替手段）。coreにより、tools/listのペイロードは206個のツール／約401 KBから32個のツール／約78 KBへと約80％縮小します。プロファイルは組み合わせて使用できます。RANCHER_TOOLSETS=core,storageとすると、トリアージ用セットにストレージ関連のツールすべてが加わります。

RANCHER_TOOLSETS=core                        # small triage surface
RANCHER_TOOLSETS=core,storage,workloads      # triage + two full families
RANCHER_TOOLS=rancher_secret_get             # add one extra tool on top
RANCHER_EXCLUDE_TOOLS=rancher_secret_create  # remove one, wins over the above

未知のプロファイル名が指定された場合は、空または縮小されたツールセットを黙って返すのではなく、起動時に明確なエラーになります。実在するツールでも、アクティブなプロファイルに含まれていなければ、ツール名、そのツールを有効にするツールセット、および設定すべき環境変数を示す構造化されたTOOLSET_NOT_ENABLEDエラーが返されます。無効化されたツールと入力ミスを区別できなくなるような、単なる「unknown tool」という応答は返しません。

プロジェクトの状況

読み取り、トリアージ、保護された書き込み操作については、リリース済みで安定しています。それ以外の状況を以下に正直に示します。

• 破壊的なワークフロー（ノードのドレイン、etcd／バックアップの復元、証明書のローテーション、クラスターのアップグレード／削除）はロードマップ上の項目です。実環境での読み取り操作の実績を積んでから段階的に対応する方針です。現在これらを必要とする運用担当者向けには、汎用エンジンと確認ガードで既に対応できます。
• Alertmanagerのルート／サイレンス機能には、クラスター内APIとの統合が必要なため、対応を延期しています。
• バージョンごとの完全な互換性マトリックス（Track G）は作業中です。最初の実環境での検証実行では、両方のターゲットの読み取りマトリックスを対象としています。

作業状況はツール単位で管理しています。docs/tool-catalog.md（各ツールに行があり、各ギャップにスライスIDがあります）とROADMAP.mdを参照してください。

開発

make help               # every target, documented
make validate           # codegen drift + manifest drift + architecture + lint + typecheck + tests
make tool-manifest      # regenerate docs/tool-manifest.json from the registry
make lab-up             # local Rancher 2.6.5 lab (kind + helm), fully scripted
make integration-current # isolated Rancher 2.14.3 end-to-end test run
make live-read-matrix   # read-only validation probes against configured instances
make mock-rancher       # fixture-backed mock Rancher for provider-config testing

• ローカルラボ — シミュレーション用の下流クラスターを備えた、kind上で動作する自己完結型のRancher 2.6.5です。リポジトリ内のkubeconfigのみを使用し、マシンの状態には一切触れません。
• 現在の統合ラボ — 別々のKindクラスター上で動作するRancher 2.14.3で、ポート9443を使用します。レガシーラボとDockerリソースの需要が重ならないよう、make integration-currentで順番に実行してください。
• コントラクト用フィクスチャ — 実環境のRancherから取得したサニタイズ済みのデータをtests/fixtures/にコミットしています。テストではrespxを使ってHTTP境界を固定します。
• コード生成 — 厳選したツールはcatalog/curated_tools/*.ymlの記述ファイルから生成されます。差異がある場合、make check-codegenは失敗します。
• ゲート — ruff、pyright strict、カバレッジ下限を設けた624件のテスト、アーキテクチャの行数制限、モジュール構成チェック、シークレットスキャンを実施します。すべて失敗時は処理を停止し、pre-commitに組み込まれています。

技術スタック：Python 3.12 · FastMCP · httpx · Pydantic v2 · structlog · uv

セキュリティ

脅威モデル、トークンに関するガイダンス、脆弱性の報告方法については、SECURITY.mdを参照してください。

ライセンス

MIT