helm-mcp

Name: helm-mcp
Author: SCGIS-Wales

ローカル

github.comクラウド・インフラ23 週間前に更新

リポジトリ公式サイト

helm-mcp について

helm-mcpは、Kubernetesデプロイを管理するAIアシスタントにHelm操作を公開するオープンソースのMCPサーバーです。ネイティブGo SDKにより、単一バイナリでHelm 3.xと4.xに対応し、stdioとStreamable HTTPを利用できます。

主な機能

01Helm CLIコマンドを網羅する46のツール
02Helm 3.xおよび4.x SDK対応
03stdioとStreamable HTTPのトランスポート
04一部ツールの構造化出力
05操作の安全性を示すツール注釈

活用シーン

01Kubernetesリリースのインストールやアップグレード
02チャートリポジトリやレジストリの検索
03リリース状態、値、履歴の確認
04Helmチャートの作成、検査、レンダリング

MCP 対応

stdioまたはStreamable HTTP経由で、MCPクライアントにHelmツール46種を公開します。HTTPはデフォルトでステートレス動作に対応し、以前のMCPプロトコルバージョンともネゴシエーションします。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "scgis-wales-helm": {
      "command": "uvx",
      "args": [
        "helm-mcp"
      ],
      "env": {
        "KUBECONFIG": "<KUBECONFIG>",
        "HELM_MCP_BINARY": "<HELM_MCP_BINARY>"
      }
    }
  }
}

起動コマンドuvx helm-mcp

設定が必要な環境変数

KUBECONFIGPath to the kubeconfig file. Defaults to ~/.kube/config.

HELM_MCP_BINARYExplicit path to the helm-mcp Go binary. Auto-detected when unset.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypihelm-mcp0.5.0stdio

ocighcr.io/scgis-wales/helm-mcp:0.5.0stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
qps	number	いいえ	クライアント側の QPS レート制限
name	string	はい	作成する chart の名前。パスも指定でき、その場合は最後の要素が chart 名になります。
debug	boolean	いいえ	デバッグ出力を有効にする
starter	string	いいえ	Starter chart：$HELM_DATA_HOME/starters 内の名前、または絶対パス
namespace	string	いいえ	Kubernetes のネームスペース
kube_token	string	いいえ	Kubernetes API 認証用の Bearer トークン
kubeconfig	string	いいえ	kubeconfig ファイルのパス（デフォルトは $KUBECONFIG または ~/.kube/config）
burst_limit	integer	いいえ	クライアント側のデフォルトのスロットリング上限
helm_version	string	いいえ	Helm SDK のバージョン：v3 または v4（デフォルト：v4）
kube_context	string	いいえ	kubeconfig の Kubernetes コンテキスト名
kube_apiserver	string	いいえ	Kubernetes API サーバーの URL（kubeconfig を上書き）
kube_insecure_tls	boolean	いいえ	TLS 証明書の検証をスキップします（安全ではありません）
kube_tls_server_name	string	いいえ	TLS 証明書の検証に使用するサーバー名

詳細

Kubernetes パッケージマネージャーである Helm にフルアクセスできる、オープンソースの MCP（Model Context Protocol）サーバーです。ネイティブの Helm Go SDK で構築されており、単一のバイナリで Helm 3.x と 4.x の両方をサポートします。

自然言語で Kubernetes のデプロイを管理できます。
helm-mcp を Claude、Cursor、VS Code、または MCP 互換のクライアントに接続して、チャートのインストール、リリースの管理、リポジトリの検索などを、すべて会話を通じて行えます。

helm-mcp を選ぶ理由
インストール
クイックスタート
MCP クライアントの設定
MCP プロトコルのサポート
利用可能なツール
ツールのアノテーション
構造化出力
Helm CLI のカバー範囲
Kubernetes 認証
Helm バージョンの選択
Python パッケージ
レジリエンスの設定（Python）
レスポンスペイロードの管理
既知の制限事項
セキュリティ
- 認証（OIDC/OAuth2）
- 代理トークン交換（OBO）
開発
アーキテクチャ
コントリビューション
コミュニティ
ライセンス

helm-mcp を選ぶ理由

46 個の MCP ツール — シェル補完とヘルプを除くすべての Helm CLI コマンドを網羅
2 種類の Helm SDK をサポート — ネイティブ Go SDK を使用して Helm v3 と v4 に対応（CLI ラッパーではありません）
2 種類のトランスポートモード — stdio（デフォルト）と Streamable HTTP。デフォルトではステートレス
クラウドプロバイダーに対応 — EKS、GKE、AKS の kubeconfig 形式をそのまま利用可能
セキュリティを最優先 — Linux プロセスの強化、認証情報のメモリ消去、入力検証、パストラバーサル防止
Python ラッパー — FastMCP ベースのプロキシで、すべてのツールを自動検出
フォワードプロキシをサポート — HTTP_PROXY、HTTPS_PROXY、NO_PROXY を尊重

インストール

ビルド済みバイナリ

GitHub Releases から、お使いのプラットフォーム向けの最新リリースをダウンロードします。

# macOS (Apple Silicon)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-darwin-arm64
chmod +x helm-mcp-darwin-arm64
sudo mv helm-mcp-darwin-arm64 /usr/local/bin/helm-mcp

# macOS (Intel)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-darwin-amd64
chmod +x helm-mcp-darwin-amd64
sudo mv helm-mcp-darwin-amd64 /usr/local/bin/helm-mcp

# Linux (amd64)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-linux-amd64
chmod +x helm-mcp-linux-amd64
sudo mv helm-mcp-linux-amd64 /usr/local/bin/helm-mcp

# Linux (arm64)
curl -LO https://github.com/SCGIS-Wales/helm-mcp/releases/latest/download/helm-mcp-linux-arm64
chmod +x helm-mcp-linux-arm64
sudo mv helm-mcp-linux-arm64 /usr/local/bin/helm-mcp

ソースからビルド

Go 1.27.2 以降が必要です。

git clone https://github.com/SCGIS-Wales/helm-mcp.git
cd helm-mcp
make build

Docker

docker build -t helm-mcp .
docker run -v ~/.kube:/home/helmuser/.kube:ro helm-mcp --mode stdio

Python パッケージ

pip install helm-mcp

詳しくは、以下のPython パッケージを参照してください。

クイックスタート

stdio モード（Claude Code、Cursor など向け）

helm-mcp --mode stdio

HTTP モード（ストリーム可能な HTTP）

helm-mcp --mode http

HTTP モードは、デフォルトで 127.0.0.1:8080 をリッスンします。リモートクライアントからの接続を受け入れるには、認証を設定し（認証を参照）、たとえば --addr 0.0.0.0:8080 のように明示的にバインドしてください。

HTTP モードは、デフォルトでステートレスです（MCP 2026-07-28）。initialize ハンドシェイクも Mcp-Session-Id ヘッダーもないため、セッションの固定化や共有セッションストアがなくても、通常のラウンドロビンロードバランサーの背後にサーバーを配置できます。古いプロトコル改訂版を使用するクライアントも引き続き動作します。SDK が自動的に古いバージョンに合わせてネゴシエーションします。

クライアントで従来のセッション単位の動作が必要な場合：

helm-mcp --mode http --stateless=false

v0.2.0 で削除：--mode sse。 HTTP+SSE トランスポートは、2025-03-26 以降 MCP 仕様で非推奨となっており、2026-07-28 の機能ライフサイクルポリシーに基づき正式に非推奨になりました。同じアドレスでストリーム可能な HTTP を提供する --mode http を使用してください。

MCP クライアントの設定

Claude Desktop

~/.claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "helm": {
      "command": "helm-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

Claude Code

claude mcp add helm -- helm-mcp --mode stdio

Cursor / Windsurf / VS Code

MCP サーバーの設定に追加します：

{
  "helm-mcp": {
    "command": "helm-mcp",
    "args": ["--mode", "stdio"]
  }
}

リモート / HTTP クライアント

サーバーを HTTP モードで起動し、MCP 互換クライアントをエンドポイントに接続します：

helm-mcp --mode http
# MCP endpoint: http://localhost:8080/mcp

MCP プロトコルのサポート

helm-mcp は MCP 2026-07-28 を実装し、古いクライアント向けに以前の改訂版（2025-11-25、2025-06-18、2025-03-26、2024-11-05）へネゴシエーションします。そのため、サーバーをアップグレードしても、クライアントをアップグレードする必要はありません。

機能	状態
ツール	サポート済み：46 個のツール。それぞれにトップレベルの `title`、アノテーション、および（結果の形式が安定している場合は）出力スキーマがあります
進捗	サポート済み。`helm_install`、`helm_upgrade`、`helm_uninstall`、`helm_rollback`、`helm_test` は、リクエストに進捗トークンが含まれている場合、10 秒ごとに `notifications/progress` のハートビートを送信します。進捗に応じてタイムアウトをリセットするクライアントは、時間のかかる `wait` 操作をそのまま待機できます
キャンセル	サポート済み。HTTP モードでは、リクエストが切断されると実行中のツール呼び出しがキャンセルされます。これは Ctrl+C で `helm` CLI がキャンセルされるのと同様です（処理を完了させるには `--propagate-cancellation=false` を指定します）
ステートレスなトランスポート	サポート済みで、`--mode http` のデフォルトです（無効にするには `--stateless=false` を指定します）
`server/discover`	サポート済み
決定的な `tools/list` の順序	サポート済み — ツールは名前順に返されるため、クライアントやプロンプトキャッシュで一貫してヒットします
サーバーの指示	サポート済み — サーバーは、バージョンの選択、クラスターの指定、破壊的なツールの安全性について説明します
リソース / プロンプト	該当なし — Helm の各操作はすべてツール呼び出しです
Tasks 拡張	未実装です。時間のかかる `helm install --wait` の実行には有用ですが、クライアントのサポートはまだ限定的です。今後の対応項目として追跡しています。
MRTR / Elicitation	意図的に未実装です。Helm のツールはすべての入力を引数として受け取るため、呼び出しの途中で質問することはありません。
Roots / Sampling / Logging	未実装です。3 つとも `2026-07-28` 時点で非推奨です（SEP-2577）。
HTTP+SSE トランスポート	v0.2.0 で削除 — 仕様で非推奨となっています。`--mode http` を使用してください。

利用可能なツール（46）

リリース管理（14）

ツール	説明
`helm_install`	新しいリリースとして Helm チャートをインストールします
`helm_upgrade`	リリースを新しいチャートバージョンまたは値にアップグレードします
`helm_uninstall`	リリースをアンインストールし、関連するリソースを削除します
`helm_rollback`	リリースを以前のリビジョンにロールバックします
`helm_list`	リリースを一覧表示します（フィルター、並べ替え、ページネーションに対応）
`helm_status`	リリースのステータス、リビジョン、チャート、値を表示します
`helm_history`	リリースのリビジョン履歴を表示します
`helm_test`	リリースのテストスイートを実行します
`helm_get_all`	リリースのすべての情報（値、マニフェスト、フック、ノート）を取得します
`helm_get_hooks`	リリースのフックを取得します
`helm_get_manifest`	リリースの Kubernetes マニフェストを取得します
`helm_get_metadata`	リリースのメタデータを取得します
`helm_get_notes`	リリースのノートを取得します
`helm_get_values`	リリースの値（ユーザー指定または計算された値）を取得します

チャート管理（14）

ツール	説明
`helm_create`	新しいチャートを作成します。スターターから作成することもできます
`helm_lint`	問題やベストプラクティスへの適合性についてチャートを lint します
`helm_template`	インストールせずにテンプレートとフックをローカルでレンダリングします
`helm_package`	チャートディレクトリをアーカイブ（.tgz）にパッケージ化します
`helm_pull`	リポジトリまたは OCI レジストリからチャートをダウンロードします
`helm_push`	チャートアーカイブを OCI レジストリにプッシュします
`helm_verify`	チャートに有効な来歴ファイルがあることを検証します
`helm_show_all`	チャートのすべての情報（Chart.yaml、値、README、CRD）を表示します
`helm_show_chart`	チャートの Chart.yaml を表示します
`helm_show_crds`	チャートの CRD を表示します
`helm_show_readme`	チャートの README を表示します
`helm_show_values`	チャートのデフォルト値を表示します
`helm_dependency_build`	Chart.lock から charts/ ディレクトリをビルドします
`helm_dependency_list`	チャートの依存関係を一覧表示します

リポジトリ管理（5）

ツール	説明
`helm_repo_add`	チャートリポジトリを追加します
`helm_repo_list`	設定済みのチャートリポジトリを一覧表示します
`helm_repo_update`	チャートリポジトリのインデックスを更新します
`helm_repo_remove`	チャートリポジトリを削除します
`helm_repo_index`	チャートアーカイブのインデックスファイルを生成します

レジストリ／OCI（2）

ツール	説明
`helm_registry_login`	OCI レジストリにログインします
`helm_registry_logout`	OCI レジストリからログアウトします

検索（2）

ツール	説明
`helm_search_hub`	Artifact Hub でチャートを検索します
`helm_search_repo`	ローカルで設定されたリポジトリを検索します

プラグイン管理（6）

ツール	説明
`helm_plugin_install`	Helm プラグインをインストールします
`helm_plugin_list`	インストール済みのプラグインを一覧表示します
`helm_plugin_uninstall`	プラグインをアンインストールします
`helm_plugin_update`	プラグインを更新します
`helm_plugin_package`	プラグインディレクトリを署名付きアーカイブにパッケージ化します（v4 のみ）
`helm_plugin_verify`	パッケージ化されたプラグインの署名と来歴を検証します（v4 のみ）

環境（2）

ツール	説明
`helm_env`	Helm の環境情報を出力します
`helm_version`	Helm SDK のバージョン情報を出力します

依存関係の更新（1）

ツール	説明
`helm_dependency_update`	Chart.yaml に基づいて charts/ を更新します

ツールのアノテーション

すべてのツールには MCP アノテーションが付与されているため、クライアントや呼び出すツールを判断するエージェントは、クラスターの読み取りと変更を一目で見分けられます。

アノテーション	意味	ツール
`readOnlyHint: true`	状態を読み取るだけなので、自由に呼び出しても安全です	`helm_list`、`helm_status`、`helm_history`、すべての `helm_get_`、すべての `helm_show_`、`helm_repo_list`、`helm_plugin_list`、`helm_dependency_list`、`helm_env`、`helm_version`、`helm_lint`、`helm_template`、`helm_verify`、`helm_plugin_verify`、`helm_search_*`
`destructiveHint: true`	稼働中の状態を削除または置換する可能性があるため、ユーザーが明示的に意図した場合にのみ呼び出してください	`helm_uninstall`、`helm_rollback`、`helm_upgrade`、`helm_repo_remove`、`helm_plugin_uninstall`
`openWorldHint: true`	設定済みのクラスターの外部（Artifact Hub、OCI レジストリ、チャートリポジトリ）にアクセスします	`helm_search_hub`、`helm_search_repo`、`helm_pull`、`helm_push`、すべての `helm_show_`、`helm_template`、すべての `helm_registry_`
`idempotentHint: true`	同じ引数で繰り返し呼び出しても、追加の影響はありません	すべての読み取り専用ツール、および `helm_repo_add`、`helm_repo_update`、`helm_dependency_*`、`helm_plugin_update`

破壊的として記載されていないものには、すべて destructiveHint: false が付与されています。これは、MCP 仕様ではこのヒントの既定値が true であるため重要です。

アノテーションはヒントであり、セキュリティ境界ではありません。クライアントが無視する可能性もあります。実際の境界を設けるには、Security で説明している OIDC スコープとロールを使用してください。

構造化出力

11 個のツールは outputSchema を公開し、人が読めるテキストとともに structuredContent を返します。そのため、クライアントは文章を解析せずに結果を利用できます。

helm_list、helm_status、helm_history、helm_get_metadata、helm_get_values、helm_repo_list、helm_search_repo、helm_search_hub、helm_plugin_list、helm_env、helm_version。

// helm_list
{
  "releases": [
    { "name": "my-app", "namespace": "default", "revision": 3, "status": "deployed", ... }
  ],
  "count": 1
}

既存の JSON テキストコンテンツは変更されないため、それを解析するクライアントは引き続き動作します。コレクションは配列のままではなく、count を含むオブジェクトでラップされます。出力が自由形式の YAML またはテキストであるツール（helm_template、helm_lint、helm_get_manifest、helm_show_*、helm_package、helm_dependency_list）には、宣言できる有用な形式がないため、出力スキーマはありません。

Helm CLI の対応状況

すべての helm CLI コマンドと、対応する helm-mcp MCP ツールの完全な一覧です。

Helm コマンド	MCP ツール	状況
`helm create`	`helm_create`	対応済み
`helm dependency build`	`helm_dependency_build`	対応済み
`helm dependency list`	`helm_dependency_list`	対応済み
`helm dependency update`	`helm_dependency_update`	対応済み
`helm env`	`helm_env`	対応済み
`helm get all`	`helm_get_all`	対応済み
`helm get hooks`	`helm_get_hooks`	対応済み
`helm get manifest`	`helm_get_manifest`	対応済み
`helm get metadata`	`helm_get_metadata`	対応済み
`helm get notes`	`helm_get_notes`	対応済み
`helm get values`	`helm_get_values`	対応済み
`helm history`	`helm_history`	対応済み
`helm install`	`helm_install`	対応済み
`helm lint`	`helm_lint`	対応済み
`helm list`	`helm_list`	対応済み
`helm package`	`helm_package`	対応済み
`helm plugin install`	`helm_plugin_install`	対応済み
`helm plugin list`	`helm_plugin_list`	対応済み
`helm plugin uninstall`	`helm_plugin_uninstall`	対応済み
`helm plugin package`	`helm_plugin_package`	対応済み（v4 のみ）
`helm plugin update`	`helm_plugin_update`	対応済み
`helm plugin verify`	`helm_plugin_verify`	対応済み（v4 のみ）
`helm pull`	`helm_pull`	対応済み
`helm push`	`helm_push`	対応済み
`helm registry login`	`helm_registry_login`	対応済み
`helm registry logout`	`helm_registry_logout`	対応済み
`helm repo add`	`helm_repo_add`	対応済み
`helm repo index`	`helm_repo_index`	対応済み
`helm repo list`	`helm_repo_list`	対応済み
`helm repo remove`	`helm_repo_remove`	対応済み
`helm repo update`	`helm_repo_update`	対応済み
`helm rollback`	`helm_rollback`	対応済み
`helm search hub`	`helm_search_hub`	対応済み
`helm search repo`	`helm_search_repo`	対応済み
`helm show all`	`helm_show_all`	対応済み
`helm show chart`	`helm_show_chart`	対応済み
`helm show crds`	`helm_show_crds`	対応済み
`helm show readme`	`helm_show_readme`	対応済み
`helm show values`	`helm_show_values`	対応済み
`helm status`	`helm_status`	対応済み
`helm template`	`helm_template`	対応済み
`helm test`	`helm_test`	対応済み
`helm uninstall`	`helm_uninstall`	対応済み
`helm upgrade`	`helm_upgrade`	対応済み
`helm verify`	`helm_verify`	対応済み
`helm version`	`helm_version`	対応済み
`helm completion`	—	対象外（シェルユーティリティ）
`helm help`	—	対象外（シェルユーティリティ）

運用に使う Helm コマンド 46 個すべてに対応しています。除外されているコマンド（completion、help）は、MCP のコンテキストでは意味を持たないシェルユーティリティです。

helm plugin package と helm plugin verify は、署名付きプラグイン配布とともに Helm v4 で導入されたため、helm_version: "v4" が必要です。

フラグのカバレッジ

コマンドは名前だけでなく、フラグも含めて網羅しています。ツールが受け付けるすべての引数は Helm SDK に渡され、レンダリングや適用の動作を変える引数は、実際のチャートをレンダリングまたはドライランするテストで網羅されています。以下のフラグは意図的に公開していません。

フラグ	理由
Helm v3 の `--post-renderer`	v3 のポストレンダラーは、サーバーホスト上の任意のバイナリを実行します。Helm v4 のポストレンダラーはインストール済みプラグインであり、`post_renderer` として公開されています
`--set` と `--set-json`	インラインの `values` オブジェクトで対応しています。これは `--set` と同様にディープマージされます
`template --output-dir`	`helm_template` は読み取り専用です。`output_dir` を指定した `helm_install` を使用してください
`create --chart-api-version v3`	Helm 4.3 では実験的機能であり、機能ゲートの背後にあります
`history --show-rollback-revision`、`get --template`、`version --template`	表示専用です。構造化された結果にすでにデータが含まれています
`search hub --endpoint`、`search --fail-on-no-result`、`repo index --json`	エージェントにとっての価値が低いため、要望に応じて追加する場合があります
`push --username/--password`、`plugin install` の TLS とレジストリ認証	まず `helm_registry_login` を使用してください。認証情報は後続の呼び出し用に保存されます

Kubernetes 認証

すべてのツールは、GlobalInput を通じて以下の認証フィールドを受け付けます。

フィールド	JSON キー	説明
Kubeconfig	`kubeconfig`	kubeconfig ファイルのパス（デフォルトは `$KUBECONFIG` または `~/.kube/config`）
コンテキスト	`kube_context`	使用する Kubernetes コンテキスト名
API サーバー	`kube_apiserver`	kubeconfig の API サーバー URL を上書きします
ベアラートークン	`kube_token`	API 認証用のベアラートークン
TLS サーバー名	`kube_tls_server_name`	TLS 証明書の検証に使用するサーバー名
TLS の検証を無効化	`kube_insecure_tls`	TLS 証明書の検証をスキップします
ネームスペース	`namespace`	対象の Kubernetes ネームスペース

EKS（AWS）

EKS は kubeconfig で exec ベースの認証を使用します。aws eks update-kubeconfig で生成された標準の kubeconfig は、そのまま動作します。

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "arn:aws:eks:us-east-1:123456789:cluster/my-cluster"
}

または、トークンを直接使った認証も可能です。

{
  "kube_apiserver": "https://ABCDEF.gr7.us-east-1.eks.amazonaws.com",
  "kube_token": "<bearer-token-from-aws-eks-get-token>"
}

GKE（Google Cloud）

gcloud container clusters get-credentials で生成された GKE kubeconfig は、そのまま動作します。

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "gke_my-project_us-central1_my-cluster"
}

AKS（Azure）

az aks get-credentials で生成された AKS kubeconfig は、そのまま動作します。

{
  "kubeconfig": "/home/user/.kube/config",
  "kube_context": "my-aks-cluster"
}

Helm バージョンの選択

すべてのツールは helm_version フィールドに対応しており、Helm v3 と v4 を選択できます。

{
  "helm_version": "v4",
  "release_name": "my-release"
}

"v4"（デフォルト）：サーバーサイド適用、プラグインベースのポストレンダラー、署名付きプラグインに対応する Helm v4 SDK
"v3"：後方互換性のための Helm v3 SDK

v4 専用機能

以下のフィールドには helm_version: "v4" が必要です。"v3" とともに指定すると、何もせずに無視されるのではなく、エラーになります。

フィールド	ツール	備考
`server_side_apply`	install、upgrade、rollback	サーバーサイド適用を参照してください。v3 ではクライアントサイド適用が常に行われるため、`false` は指定できます
`force_conflicts`	install、upgrade、rollback	他のフィールドマネージャーが所有するフィールドの所有権を取得します
`wait_strategy`	install、upgrade、rollback、uninstall	下記を参照してください
`post_renderer`、`post_renderer_args`	install、upgrade、template	インストール済みのポストレンダラープラグインの名前
`description`	rollback	ロールバックのリビジョンに記録される説明
`verify`、`keyring`	plugin install	`verify: false` は helm-diff などの未署名プラグインをインストールします

2 つのツールは、ツール全体が v4 専用です。helm_plugin_package と helm_plugin_verify です。

サーバーサイド適用

Helm 4 はデフォルトで Kubernetes のサーバーサイド適用を行います。helm_install も同様です。サーバーサイド適用を使う場合は server_side_apply を未設定のままにし、クライアントサイド適用を使う場合は false に設定します。helm_upgrade と helm_rollback では、未設定の場合、Helm の auto モードが維持され、以前のリリースに記録された適用方法が再利用されます。リリース結果では、適用方法は apply_method（"ssa" または "csa"）として報告されます。

v0.5.0 より前は、server_side_apply が true でない限り、v4 エンジンはすべてのインストールとロールバックでクライアントサイド適用を強制していました。クライアントサイド適用を利用する場合は、server_side_apply: false を指定してください。

待機：`wait` と `wait_strategy`

Helm v4 では、v3 のブール値の --wait が戦略を表す列挙値に置き換えられました。そのため、helm_install、helm_upgrade、helm_rollback、helm_uninstall では、wait とともに wait_strategy フィールドを指定できます。

`wait_strategy`	動作
`"watcher"`	kstatus を使用して待機します。v4 で `helm --wait` を指定した場合と同じです
`"legacy"`	v3 の準備状況チェックを使用して待機します
`"hookOnly"`	フックのみを待機します。`--wait` を省略した場合の CLI のデフォルトです

wait_strategy が設定されている場合は、そちらが優先されます。それ以外の場合、wait: true は "watcher" に、wait: false は "hookOnly" に対応します。

v0.2.0 より前は、v4 エンジンで watcher 戦略がハードコードされていたため、wait: false は無視され、すべての v4 操作で待機が行われていました。この動作に依存していた場合は、wait: true（または wait_strategy: "watcher"）を明示的に設定してください。

v3 と v4 の両方で利用可能

rollback_on_failure（Helm の --atomic）は両方のエンジンでサポートされており、helm_install と helm_upgrade で利用できます。また、devel、sub_notes、hide_notes、skip_schema_validation、disable_openapi_validation、enable_dns、take_ownership、hide_secret、helm_install の output_dir、use_release_name、force_replace、helm_upgrade の reset_then_reuse_values、helm_uninstall の ignore_not_found、description、helm_list の all、uninstalling、time_format、selector、helm_status の show_resources、helm_test の logs、および helm_show_* ツールの jsonpath も利用できます。

チャートのソース

helm_install、helm_upgrade、helm_template、helm_pull、および helm_show_* ツールでは、Helm のチャートロケーションフラグ（repo、username、password、ca_file、cert_file、key_file、insecure_skip_tls_verify、plain_http、pass_credentials、verify、keyring）を指定できます。TLS と認証情報のオプションは oci:// チャートにも適用されます。

verify は、CLI と同様に、デフォルトで $GNUPGHOME/pubring.gpg（または ~/.gnupg）を使用するキーリングに対してチャートの来歴を検証します。helm_pull の prov は、来歴ファイルを検証せずにダウンロードします（helm pull --prov）。

アップグレードまたはインストール

install: true を指定した helm_upgrade は、リリースが存在しない場合にインストールし、最後のリビジョンがアンインストール済みの場合は置き換えます。これは helm upgrade --install とまったく同じ動作です。create_namespace はこのインストールにも適用されます。

値

値は Helm が使用する順序で結合されます。まず values_files、次にインラインの values オブジェクト（--set と同様にディープマージ）、続いてそれぞれ key=value 文字列のリストである set_string、set_file、set_literal の順です。set_file が読み込むのはローカルファイルのみです。また、{a,b} リスト内や、さらにカンマで区切られたペア内のパスを含め、読み込み対象となるすべてのパスが検証されます。

チャートの依存関係

helm_install、helm_upgrade、helm_template の dependency_update は、CLI フラグと同様に、レンダリング前に不足している依存関係を取得します。これを指定しない場合、依存関係がチャートに同梱されていないチャートは、サブチャートをレンダリングせずにエラーとして報告されます。

Python パッケージ

FastMCP を使用して helm-mcp Go バイナリの透過的なプロキシを作成する Python ラッパーを利用できます。Go バイナリに追加された新しいツールは、コードを変更しなくても Python から自動的に利用できます。

インストール

pip install helm-mcp

Python 3.12 以降が必要です。Go バイナリはプラットフォーム固有の wheel に同梱されているため、Go ツールチェーンは不要です。サポート対象のプラットフォーム：linux-amd64、linux-arm64、darwin-amd64、darwin-arm64、windows-amd64。バイナリは初回使用時に wheel から展開され、改ざん防止のため SHA256 チェックサム検証が行われます。

バイナリが利用可能であることを確認できます。

helm-mcp-python --setup

サーバーとしての使用

from helm_mcp import create_server

# stdio mode (default, for MCP clients)
server = create_server()
server.run()

# HTTP mode
server = create_server()
server.run(transport="http", host="127.0.0.1", port=8080)

クライアントとしての使用

import asyncio
from helm_mcp import create_client

async def main():
    async with create_client() as client:
        # List all available tools
        tools = await client.list_tools()
        print(f"Available tools: {len(tools)}")

        # List Helm releases
        result = await client.call_tool("helm_list", {"namespace": "default"})
        print(result)

        # Install a chart
        result = await client.call_tool("helm_install", {
            "release_name": "my-app",
            "chart": "bitnami/nginx",
            "namespace": "default",
        })
        print(result)

asyncio.run(main())

CLI

# stdio mode (for MCP clients like Claude Code)
helm-mcp-python

# HTTP mode (loopback only by default; the Python proxy has no authentication)
helm-mcp-python --transport http --port 8080

# Bind to all interfaces only behind your own authenticating proxy
helm-mcp-python --transport http --host 0.0.0.0 --allow-remote

# Custom binary path
helm-mcp-python --binary /usr/local/bin/helm-mcp

FastMCP との統合

Python パッケージは FastMCP を基盤として構築されており、標準の FastMCP サーバー／クライアントオブジェクトを返します。他の FastMCP サーバーと組み合わせて使用できます。

from fastmcp import FastMCP
from helm_mcp import create_server as create_helm_server

# Create a composite server
app = FastMCP("my-platform")

# Mount helm-mcp as a sub-server
helm = create_helm_server()
app.mount("helm", helm)

# Add your own tools alongside Helm
@app.tool()
def my_custom_tool(param: str) -> str:
    return f"Custom: {param}"

app.run()

バイナリの検出

Python パッケージは、次の順序で helm-mcp Go バイナリを検索します。

HELM_MCP_BINARY 環境変数
パッケージの bin/ ディレクトリに同梱されたバイナリ
GitHub Releases からの自動ダウンロード（SHA256 チェックサム検証付き）
PATH 上の helm-mcp

環境変数

プロキシは、以下の環境変数を Go サブプロセスに転送します。

カテゴリ	変数
プロキシ	`HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`（および小文字の表記）
Kubernetes	`KUBECONFIG`、`KUBERNETES_SERVICE_HOST`、`KUBERNETES_SERVICE_PORT`
Helm	`HELM_CACHE_HOME`、`HELM_CONFIG_HOME`、`HELM_DATA_HOME`、`HELM_PLUGINS`、`HELM_DEBUG`
AWS	`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN`、`AWS_REGION`、`AWS_PROFILE`
GCP	`GOOGLE_APPLICATION_CREDENTIALS`、`CLOUDSDK_COMPUTE_ZONE`
Azure	`AZURE_TENANT_ID`、`AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`、`AZURE_SUBSCRIPTION_ID`
TLS	`SSL_CERT_FILE`、`SSL_CERT_DIR`

レジリエンス設定（Python）

Python パッケージには、FastMCP のミドルウェア、circuitbreaker、tenacity を基盤とする包括的なレジリエンス機能が含まれています。すべての設定は、適切なデフォルト値が設定された HELM_MCP_* 環境変数で変更できます。

環境変数

変数	型	デフォルト	説明
`HELM_MCP_RETRY_ENABLED`	bool	`true`	プロキシレベルの再試行ミドルウェアを有効にします
`HELM_MCP_RETRY_MAX_RETRIES`	int	`2`	最大再試行回数
`HELM_MCP_RETRY_BASE_DELAY`	float	`1.0`	初回のバックオフ遅延（秒）
`HELM_MCP_RETRY_MAX_DELAY`	float	`30.0`	最大バックオフ遅延（秒）
`HELM_MCP_RETRY_BACKOFF_MULTIPLIER`	float	`2.0`	バックオフ倍率
`HELM_MCP_RATE_LIMIT_ENABLED`	bool	`false`	トークンバケット方式のレート制限を有効にします
`HELM_MCP_RATE_LIMIT_MAX_RPS`	float	`10.0`	1 秒あたりの最大リクエスト数（0 より大きい値が必要です）
`HELM_MCP_RATE_LIMIT_BURST`	int	`20`	バースト容量（1 以上が必要です。不正な値の場合、起動時に失敗します）
`HELM_MCP_CACHE_ENABLED`	bool	`false`	TTL ベースのレスポンスキャッシュを有効にします
`HELM_MCP_CACHE_TOOL_TTL`	int	`300`	ツール呼び出しキャッシュの TTL（秒）
`HELM_MCP_CACHE_LIST_TTL`	int	`60`	ツール一覧キャッシュの TTL（秒）
`HELM_MCP_ERROR_HANDLING_ENABLED`	bool	`true`	構造化エラーレスポンスを有効にします
`HELM_MCP_ERROR_INCLUDE_TRACEBACK`	bool	`false`	エラーにトレースバックを含めます
`HELM_MCP_TIMING_ENABLED`	bool	`true`	リクエストの計測を有効にします
`HELM_MCP_TIMING_DETAILED`	bool	`false`	詳細な計測ミドルウェアを使用します
`HELM_MCP_CIRCUIT_BREAKER_ENABLED`	bool	`true`	ツール呼び出しのサーキットブレーカーを有効にします
`HELM_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD`	int	`5`	サーキットが開くまでの失敗回数
`HELM_MCP_CIRCUIT_BREAKER_RESET_TIMEOUT`	float	`30.0`	ハーフオープン状態で再試行するまでの秒数
`HELM_MCP_TENACITY_ENABLED`	bool	`true`	ジッター付きの tenacity 再試行を有効にします
`HELM_MCP_TENACITY_MAX_ATTEMPTS`	int	`3`	最大再試行回数
`HELM_MCP_TENACITY_MIN_WAIT`	float	`0.5`	再試行間の最小待機時間（秒）
`HELM_MCP_TENACITY_MAX_WAIT`	float	`10.0`	再試行間の最大待機時間（秒）
`HELM_MCP_TENACITY_MULTIPLIER`	float	`1.5`	指数バックオフの基準値
`HELM_MCP_BULKHEAD_ENABLED`	bool	`true`	同時実行数の制限を有効にします
`HELM_MCP_BULKHEAD_MAX_CONCURRENT`	int	`10`	同時に実行できるツール呼び出しの最大数
`HELM_MCP_OTEL_ENABLED`	bool	`false`	OpenTelemetry トレーシングを有効にします
`HELM_MCP_OTEL_SERVICE_NAME`	str	`helm-mcp`	OTel サービス名
`HELM_MCP_OTEL_EXPORTER`	str	`console`	OTel エクスポーター（`console` または `otlp`）

CLI フラグ

helm-mcp-python --no-retry                   # Disable proxy retry middleware
helm-mcp-python --rate-limit 50              # Enable rate limiting at 50 rps
helm-mcp-python --cache                      # Enable response caching
helm-mcp-python --no-circuit-breaker         # Disable circuit breaker
helm-mcp-python --bulkhead-max 5             # Limit to 5 concurrent tool calls
helm-mcp-python --otel                       # Enable OpenTelemetry tracing

プログラムによる設定

from helm_mcp import create_server, HelmClient
from helm_mcp.resilience import (
    ResilienceConfig,
    RateLimitConfig,
    CircuitBreakerConfig,
    BulkheadConfig,
)

# Server with custom resilience
config = ResilienceConfig(
    rate_limit=RateLimitConfig(enabled=True, max_requests_per_second=50),
    circuit_breaker=CircuitBreakerConfig(failure_threshold=3),
    bulkhead=BulkheadConfig(max_concurrent=20),
)
server = create_server(resilience=config)

# Client with custom resilience
async with HelmClient(resilience=config) as helm:
    releases = await helm.list(namespace="default")

OpenTelemetry

FastMCP は OpenTelemetry API を介してトレースを出力します。実際のトレースデータを受信するには、SDK をインストールしてください。

pip install helm-mcp[otel]

次に、トレーシングを有効にします。

export HELM_MCP_OTEL_ENABLED=true
export HELM_MCP_OTEL_EXPORTER=otlp        # or "console"
export HELM_MCP_OTEL_SERVICE_NAME=helm-mcp

レスポンスペイロードの管理

大きな Helm 出力（マニフェスト、値、テンプレートのレンダリング結果）は、LLM のコンテキストウィンドウを超えることがあります。helm-mcp には、これを防ぐためのレスポンスサイズ管理機能が 2 層用意されています。

レスポンスの切り詰め

すべてのツールレスポンスは、設定可能なサイズ上限を超えると自動的に切り詰められます。デフォルトは 256 KB（約 64K トークン）です。切り詰められたレスポンスには、元のサイズを示すメタデータと、より具体的なクエリを使用するための提案が含まれます。

CLI フラグまたは環境変数で上限を設定します。

# CLI flag (in bytes, 0 to disable)
helm-mcp --mode stdio --max-response-bytes 524288

# Environment variable
export HELM_MCP_MAX_RESPONSE_BYTES=524288
helm-mcp --mode stdio

CLI フラグは環境変数より優先されます。

マニフェストのサニタイズ

Kubernetes YAML を返すツール（helm_get_manifest、helm_get_all、helm_get_hooks、helm_template）は、結果を返す前にノイズとなるフィールドを自動的に削除します。これにより、通常、意味のある情報を失うことなく、マニフェストのサイズを**40〜60%**削減できます。

削除されるフィールド：

metadata.managedFields — Kubernetes の内部管理用データ（単一のフィールドとして最大になることがよくあります）
kubectl.kubernetes.io/last-applied-configuration — オブジェクト全体の冗長なコピー
deployment.kubernetes.io/revision — コントローラーの内部アノテーション
control-plane.alpha.kubernetes.io/leader — リーダー選出データ

これらのフィールドは LLM とのやり取りで役立つことがないため、このサニタイズは常に有効で、無効にはできません。元のサニタイズされていないデータは、直接 kubectl を使って引き続き利用できます。

レジリエンスの基本機能

internal/resilience パッケージは、本番環境向けの追加のレジリエンスパターンを提供します。

パターン	説明
サーキットブレーカー	バックエンドが利用できない場合に素早く失敗するための、3 状態（Closed/Open/HalfOpen）パターンです。失敗のしきい値と復旧タイムアウトを設定できます。
バックオフ付きリトライ	一時的な失敗に対する、ジッター付きの指数バックオフです。コンテキストを考慮したキャンセルと、リトライ可能なエラーのフィルタリングに対応しています。
ツールごとのタイムアウト	カテゴリ別のデフォルトタイムアウトです。query（30s）、mutate（120s）、chart（60s）、repo（60s）に設定されています。既存のコンテキスト期限を尊重します。

既知の制限事項

プラグインツールは Helm CLI を使用します

6 つすべてのプラグインツールは、システムの helm CLI をシェルから呼び出します。これは、Helm のプラグインパッケージが内部実装であり、インポートできないため、Helm Go SDK を経由しない helm-mcp の唯一の部分です。

Helm v4 では、デフォルトでプラグインの署名が検証されます。helm-diff などの署名されていないプラグインは、verify: false を指定して helm_plugin_install でインストールしてください。
公開されているコンテナーイメージには、固定された helm CLI が含まれているため、そこでプラグインツールを使用できます。バイナリを直接実行する場合は、helm が PATH にある必要があります。また、デフォルトの helm_version: "v4" を使用する場合は Helm v4 CLI が必要です。v3 CLI では --verify=false などの v4 フラグが拒否されます。

セキュリティ

プロセスの強化（Linux）

Linux で実行する場合、helm-mcp は起動時にプロセスレベルの強化を適用し、stdio トランスポートの攻撃対象領域を縮小します。IDE の子プロセスとして実行される MCP サーバーは、ユーザーのすべての権限を継承します。これらの緩和策により、プロセスが侵害された場合に攻撃者が実行できることを制限します。

仕組み	内容
PR_SET_DUMPABLE(0)	`ptrace` によるアタッチ、コアダンプ、`/proc/pid/mem` の読み取りをブロックします。他のプロセスがメモリー内の認証情報を調べるのを防ぎます。
ケイパビリティの削除	バウンディングセットからすべての Linux ケイパビリティを削除します。root 以外のユーザー（一般的なケース）では何もしませんが、設定に不備のある Docker/Kubernetes 環境で実行する場合に権限昇格を防ぎます。
認証情報のメモリー消去	各ツールハンドラーの完了後に `defer` 経由で `ZeroCredentials()` を呼び出し、メモリー内のベアラートークンとパスワードを上書きします。これは多層防御です。Go の文字列は不変で、GC がコピーを保持する可能性がありますが、コードパス内で認証情報が存続する時間を短縮します。

強化はベストエフォートであり、失敗しても致命的ではありません。失敗は（--debug を指定した場合に）ログに記録されますが、プロセスがクラッシュすることはありません。Linux 以外のプラットフォーム（macOS、Windows）では、情報ログを出力して強化をスキップします。

# Verify hardening is active (Linux)
helm-mcp --mode stdio --debug 2>&1 | grep "security hardening"

# Disable for debugging (e.g., when using strace or delve)
helm-mcp --mode stdio --no-harden

評価したが実装しなかった仕組み

仕組み	採用しなかった理由
Seccomp BPF	サーバーはプラグインに `exec.CommandContext` を使用し、Kubernetes API およびレジストリとの通信にネットワーク I/O を使用します。カーネルのバージョンをまたいで Helm SDK の内部処理を壊さずに安全にフィルタリングするには、システムコールの対象範囲が広すぎます。
Namespace isolation	プロセスには `~/.kube/config`、クラウド認証情報ファイル、DNS、ネットワークへのアクセスが必要です。Namespace isolation を導入すると、コア機能が動作しなくなります。
Cgroup resource limits	5 分の `pluginExecTimeout` によって、すでに暴走する処理の実行時間が制限されており、プロセスのライフサイクルは IDE が管理します。
AppArmor/SELinux profiles	動的なファイルパスのメンテナンス負荷が高いためです。バイナリに組み込むのではなく、外部のアーティファクトとしてデプロイする方が適しています。

認証情報のマスキング

すべてのエラーメッセージから、以下の情報が自動的にマスキングされます。

Bearer トークン（EKS、GKE、Azure の JWT トークンを含む）
Basic 認証情報
URL に埋め込まれたパスワード（https://user:password@host）

入力の検証

すべてのツールハンドラーは実行前に ValidateGlobalInput を呼び出し、すべてのリクエストで namespace と kubeconfig のフィールドが検証されるようにします。

セキュリティパッケージは以下の検証機能を提供します。

リリース名（DNS-1123 準拠）
Namespace 名
Kubeconfig ファイルパス（パストラバーサルの防止、シンボリックリンクの検出、機密パスの拒否 — /etc/shadow、/proc/、/dev/、/sys/ はブロックされます）
URL（スキームの検証と SSRF 保護：DNS 解決時に、0.0.0.0/8、127.0.0.0/8、10.0.0.0/8、100.64.0.0/10、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、IPv4 マップドアドレス、NAT64、および IPv6 の未指定・ループバック・リンクローカル・ユニークローカル範囲のプライベート IP をブロックします）。リポジトリ URL、URL 形式のチャート参照、リモートの values ファイル、OCI のプッシュ先に適用されます
ファイルパス（トラバーサルの防止、親ディレクトリのシンボリックリンクを含むシンボリックリンクの拒否、機密パスの拒否）。values ファイル、set_file エントリー、キーリング、CA／証明書／鍵ファイル、パスフレーズファイル、出力先と untar ディレクトリ、helm_lint と helm_package のチャートパス、および helm_create のチャート名と starter に適用されます
リポジトリ名（英数字、ピリオド、ダッシュ、アンダースコア。キャッシュパスのトラバーサルを防止）
タイムアウト時間（最大 24h）
プラグイン名（英数字とダッシュ／アンダースコア。引数インジェクションを防ぐため、先頭のダッシュは使用不可）

ファイル権限

リポジトリの設定ファイルは 0600（所有者のみ読み取り／書き込み可能）で書き込まれます
設定ディレクトリは 0700（所有者のみアクセス可能）で作成されます

HTTP サーバーの強化

HTTP モードで実行する場合：

--addr で別のアドレスが指定されない限り、127.0.0.1:8080 で待ち受けます
ReadHeaderTimeout: 10s と ReadTimeout: 30s — 遅いクライアントによる攻撃を防ぎます
WriteTimeout: 30m（--write-timeout）— wait を指定した helm_install／helm_upgrade に十分な時間です。クライアントがより長い Helm タイムアウトを使用する場合は、値を引き上げてください
リクエストが切断されると、そのツール呼び出しはキャンセルされます（--propagate-cancellation はデフォルトで有効）。これにより、放棄された操作が書き込みタイムアウトまで実行され続けることはありません
IdleTimeout: 120s — アイドル状態の接続を解放します
MaxHeaderBytes: 1MB — ヘッダーベースの DoS を防ぎます
5 秒のタイムアウトを設定したグレースフルシャットダウン

認証（OIDC/OAuth2）

HTTP モードで実行する場合、helm-mcp は JWT 検証、クレームベースの認可、構造化された監査ログを備えた OAuth2/OIDC 認証をサポートします。これは MCP セキュリティのベストプラクティスに準拠しています。

認証は完全にオプトインです。 OIDC またはトークンの環境変数が設定されていない場合、サーバーは認証なしで実行されます（以前のバージョンと同じです）。Stdio モードは認証設定の影響を受けません。

クイックスタート — Entra ID（Azure AD / ADFS）

# Required: issuer and audience
export HELM_MCP_OIDC_ISSUER="https://login.microsoftonline.com/{tenant-id}/v2.0"
export HELM_MCP_OIDC_AUDIENCE="api://helm-mcp-server"

# Optional: restrict access by scopes, roles, or client app IDs
export HELM_MCP_REQUIRED_SCOPES="helm.read,helm.write"
export HELM_MCP_REQUIRED_ROLES="HelmOperator"
export HELM_MCP_ALLOWED_CLIENTS="client-app-id-1,client-app-id-2"

# Optional: explicit JWKS URL (auto-discovered from issuer if omitted)
export HELM_MCP_OIDC_JWKS_URL="https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys"

helm-mcp --mode http --addr 0.0.0.0:8080

認証イベント（auth_success、auth_failure）は、--debug の設定にかかわらず、Info レベルの JSON として stderr に出力されます。

環境変数

変数	必須	説明
`HELM_MCP_OIDC_ISSUER`	はい（OIDC の場合）	OIDC 発行者 URL です。トークンの `iss` クレームと一致する必要があります。
`HELM_MCP_OIDC_AUDIENCE`	はい（OIDC の場合）	想定される `aud` クレームです。他のリソース向けに発行されたトークンは拒否されます。
`HELM_MCP_OIDC_JWKS_URL`	いいえ	署名検証用の JWKS エンドポイントです。省略した場合は、発行者から自動検出されます。
`HELM_MCP_REQUIRED_SCOPES`	いいえ	`scp` クレームで必須となる OAuth2 スコープを、カンマ区切りで指定します。
`HELM_MCP_REQUIRED_ROLES`	いいえ	`roles` クレームで必須となるアプリロールを、カンマ区切りで指定します。
`HELM_MCP_ALLOWED_CLIENTS`	いいえ	`azp`／`appid` クレームで許可するクライアントアプリ ID を、カンマ区切りで指定します。
`HELM_MCP_SESSION_TTL`	いいえ	セッションキャッシュの非アクティブ時の TTL（Go の期間形式。例：`5m`、`15m`）です。デフォルト：`5m`。
`HELM_MCP_AUTH_TOKEN`	いいえ	静的ベアラートークン（レガシー）です。OIDC より優先度は低くなります。

認証の優先順位

OIDC/OAuth2 — HELM_MCP_OIDC_ISSUER が設定されている場合、JWKS による JWT 検証が有効になります。
静的ベアラートークン — HELM_MCP_AUTH_TOKEN のみが設定されている場合、定時間比較が使用されます。
認証なし — どちらも設定されていない場合、サーバーはすべてのリクエストを受け付けます（ローカルの stdio 使用に適しています）。

トークンの検証

受信するすべての JWT は、次の項目について検証されます。

チェック項目	説明
署名	JWKS の公開鍵に対して RSA 署名を検証します（RS256/384/512）。鍵は 1 時間キャッシュされ、`kid` が見つからない場合は自動更新されます（鍵ローテーション）。
発行者（`iss`）	`HELM_MCP_OIDC_ISSUER` と完全に一致する必要があります。
対象者（`aud`）	`HELM_MCP_OIDC_AUDIENCE` と一致する必要があります。他の API 向けに発行されたトークンは拒否されます。これはトークンのパススルーを防ぐための中核的な対策です。
有効期限（`exp`）	必須です。期限切れのトークンは拒否されます。
認可パーティ（`azp`／`appid`）	設定されている場合は、`HELM_MCP_ALLOWED_CLIENTS` と照合されます。OIDC の `azp` と Entra ID v1 の `appid` クレームの両方に対応しています。
スコープ（`scp`）	スペース区切りのスコープを `HELM_MCP_REQUIRED_SCOPES` と照合します。
ロール（`roles`）	アプリロールの配列を `HELM_MCP_REQUIRED_ROLES` と照合します。

セッションキャッシュ

検証済みトークンは、JWKS の重複した検索を避けるため、メモリ内にキャッシュされます。

非アクティブ時の TTL：デフォルトは 5 分です（HELM_MCP_SESSION_TTL で設定可能。例：5m、10m、1h）。
トークンの有効期限：キャッシュされたトークンは、exp クレームの期限を超えて使用されることはありません。
キャッシュキー：生のベアラートークンの SHA-256 ハッシュ（トークンそのものがメモリに保存されるのを防ぎます）。
スライディングウィンドウ：アクセスのたびに非アクティブタイマーがリセットされます。
最大エントリ数：10,000 件（上限を超えると最も古いエントリが削除されます）。

監査ログ

OIDC 認証が有効な場合、認証の試行ごとに slog を通じて構造化監査イベントが出力されます。

level=INFO msg=security_audit audit.event_type=auth_success audit.principal_id=oid-123 [email protected] audit.tenant_id=tenant-abc audit.client_app_id=client-1 audit.scopes="helm.read helm.write" audit.token_id=uti-xyz audit.remote_addr=10.0.0.1:54321

監査イベントには、プリンシパル ID／名前、テナント ID、クライアントアプリ ID、スコープ、ロール、トークン ID、セッション ID、アクション、リソース、結果、所要時間、リモートアドレスが含まれます。監査情報をすべて確認するには --debug を有効にするか、ログアグリゲーターで security_audit メッセージを収集するよう設定してください。

オンビハーフオブ（OBO）トークン交換

helm-mcp が認証済みユーザーに代わって下流 API（Kubernetes API など）を呼び出す必要がある場合、受信したトークンを、その下流サービスを対象とする新しいトークンと交換します。これにより、元のトークンを転送せずに済みます。元のトークンを転送すると、下流サービスが侵害された場合や、トークンの対象者が一致しない場合に悪用される可能性があります。

仕組み

User        MCP Client        helm-mcp (MCP Server)      Kubernetes API
 │              │                      │                        │
 ├─(SSO)──────▶│ gets token            │                        │
 │              │ aud=helm-mcp          │                        │
 │              ├─(Bearer token)──────▶│                        │
 │              │                      ├─OBO exchange──────────▶│
 │              │                      │ grant_type=jwt-bearer   │
 │              │                      │ assertion=user token    │
 │              │                      │ scope=K8s API scopes    │
 │              │                      │◀─new token──────────────│
 │              │                      │  aud=Kubernetes API     │
 │              │                      ├─(K8s API call)────────▶│
 │              │                      │  with OBO token         │

チェーン内の各ホップでは、次の処理が行われます。

受信したトークンの対象者を検証します（このサーバーと一致する必要があります）。
OBO を通じて、次のサービスを対象とする新しいトークンに交換します。
元のユーザーの ID を新しいトークンのクレームに保持します。
（Entra ID で設定されている場合）Conditional Access の評価を新たに実行します。

OBO の設定

# OBO token exchange (for downstream API calls with user context)
export HELM_MCP_OBO_TOKEN_URL="https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token"
export HELM_MCP_OBO_CLIENT_ID="helm-mcp-app-id"
export HELM_MCP_OBO_CLIENT_SECRET="helm-mcp-client-secret"

トークンを転送しない理由

ユーザーのトークンを下流サービスに転送するのは魅力的ですが、問題があります。MCP Security Best Practices では、これを明確に推奨していません。OBO を使用すると、各サービスにはそのサービス独自のオーディエンス向けに発行されたトークンが渡され、必要な権限だけにスコープが限定されます。トークンが傍受された場合でも、影響範囲はチェーン全体ではなく、単一のサービスに限定されます。

AWS EKS と OBO のサポート

OIDC を使用する AWS EKS 1.34+

AWS EKS は EKS 1.21 からクラスター認証用の OIDC ID プロバイダーをサポートしており、1.34 以降では大幅に改善されています。ただし、EKS は Kubernetes API 認証における Entra ID OBO フローをネイティブにサポートしていません。認証パターンは次のように異なります。

パターン	サポート状況	詳細
EKS OIDC Identity Provider	はい	EKS で Entra ID を OIDC プロバイダーとして設定します。ユーザーは `aud` = EKS cluster の Entra ID トークンを使用して直接認証します。OBO は不要です。トークンはクラスター向けに直接発行されます。
IRSA (IAM Roles for Service Accounts)	はい	投影されたサービスアカウントトークンを使用する、Pod レベルの ID です。これは M2M（クライアント資格情報）であり、ユーザー委任ではありません。
EKS Pod Identity	はい（EKS 1.34+）	EKS Pod Identity Agent を使用した、簡素化された Pod ID です。こちらも M2M であり、ユーザー委任ではありません。
OBO → Kubernetes API	部分的	Entra ID OBO は、登録済みの任意のリソース向けにトークンを発行できます。EKS が Entra ID を OIDC プロバイダーとして設定されており、Kubernetes API が Entra ID のアプリとして登録されていれば、OBO で発行されたトークンを EKS の認証に使用できます。EKS OIDC プロバイダーでカスタムの `--oidc-issuer-url`、`--oidc-client-id`、`--oidc-username-claim` の設定が必要です。

EKS に推奨されるパターン：Entra ID を EKS OIDC ID プロバイダーとして設定します。MCP クライアントはユーザーを認証し、aud = helm-mcp のトークンを取得します。helm-mcp はこのトークンを検証し、その後 OBO 交換を実行して、aud = EKS cluster OIDC client ID の新しいトークンを取得します。この OBO で発行されたトークンを Kubernetes API 呼び出しに使用することで、ユーザー ID を維持し、ユーザーごとの RBAC を有効にします。

AWS Labs MCP と OBO

AWS Labs MCP サーバー（例：awslabs/mcp）と Amazon Bedrock AgentCore は、OAuth2 OBO または RFC 8693 Token Exchange を実装していません。AgentCore は別のモデルを使用します。

ユーザー ID の伝播：不透明な X-Amzn-Bedrock-AgentCore-Runtime-User-Id HTTP ヘッダーを介して行います。暗号学的に署名されたトークンではありません
送信時の認証：OAuth Authorization Code（3Lo）または Client Credentials（2Lo）を使用しますが、これらは委任された ID の伝播ではなく、個別の認証イベントです
Token Vault：サードパーティサービス向けのリフレッシュトークンを保存しますが、これはエージェントのスコープに限定され、ユーザー委任ではありません

つまり、AWS Labs MCP サーバーは Entra ID OBO チェーンにネイティブには参加できません。AWS ホスト型 MCP サーバーを介したユーザー委任 ID の伝播がアーキテクチャ上必要な場合は、カスタムのミドルウェアレイヤーとして OBO 交換を実装するか、helm-mcp に組み込まれた OBO サポートをリファレンス実装として使用する必要があります。

フォワードプロキシのサポート

helm-mcp は標準的なプロキシ環境変数を尊重します。

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.company.com

開発

前提条件

Go 1.27.2+
Python 3.12+（Python パッケージ用）
golangci-lint v2（任意。リンティング用）

ビルド

make build        # Build binary
make install      # Install to $GOPATH/bin
make build-all    # Cross-compile for Linux/macOS (amd64/arm64)

テスト

# Go tests
make test         # Run all tests with race detection and coverage
make test-short   # Run tests without integration tests

# Python tests
cd python && pip install -e ".[dev]" && pytest -v tests/

リント

make lint         # Run golangci-lint + go vet
make vet          # Run go vet only

セキュリティチェック

make security     # Run govulncheck

カバレッジ

make coverage     # Generate coverage report (coverage.html)

アーキテクチャ

cmd/helm-mcp/          Entry point, transport selection, CLI flags
internal/
  helmengine/           Engine interface and shared types
    v3/                 Helm v3 SDK implementation
    v4/                 Helm v4 SDK implementation
  tools/                MCP tool handlers
    release/            Install, upgrade, uninstall, rollback, list, status, etc.
    chart/              Create, lint, template, package, pull, push, show, etc.
    repo/               Add, list, update, remove, index
    registry/           Login, logout
    search/             Hub, repo
    plugin/             Install, list, uninstall, update, package, verify
    env/                Env, version
  security/             Process hardening, input validation, credential scrubbing
  resilience/           Response budget, circuit breaker, retry, timeouts, manifest sanitisation
  server/               MCP server creation and tool registration
python/                 FastMCP-based Python wrapper
  src/helm_mcp/         Python package source
  tests/                Python tests

コントリビューション

コミュニティからのコントリビューションを歓迎します！バグ報告、機能リクエスト、ドキュメントの改善、コードのコントリビューションなど、どのようなご協力もありがたく受け止めます。

詳しいガイドラインについては、CONTRIBUTING.md をご覧ください。

開発環境のセットアップ
テストとリンターの実行
プルリクエストの提出
コミットメッセージの規約

コミュニティ

バグ報告と機能リクエスト：GitHub Issues
ディスカッションと質問：GitHub Discussions
リリース：GitHub Releases（main へのマージごとに自動公開されます）

ライセンス

このプロジェクトは MIT License の下でライセンスされています。自由に使用、変更、配布できます。

Markdown 対応

ログインしてコメント

基本情報

作者: SCGIS-Wales
言語: python
バージョン: 0.5.0
トランスポート: stdio
掲載日: 2026年10月10日
最終更新: 3 週間前
公式 Registry: io.github.SCGIS-Wales/helm-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

helm-mcp

helm-mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

目次

helm-mcp を選ぶ理由

インストール

ビルド済みバイナリ

ソースからビルド

Docker

Python パッケージ

クイックスタート

stdio モード（Claude Code、Cursor など向け）

HTTP モード（ストリーム可能な HTTP）

MCP クライアントの設定

Claude Desktop

Claude Code

Cursor / Windsurf / VS Code

リモート / HTTP クライアント

MCP プロトコルのサポート

利用可能なツール（46）

リリース管理（14）

チャート管理（14）

リポジトリ管理（5）

レジストリ／OCI（2）

検索（2）

プラグイン管理（6）

環境（2）

依存関係の更新（1）

ツールのアノテーション

構造化出力

Helm CLI の対応状況

フラグのカバレッジ

Kubernetes 認証

EKS（AWS）

GKE（Google Cloud）

AKS（Azure）

Helm バージョンの選択

v4 専用機能

サーバーサイド適用

待機：wait と wait_strategy

v3 と v4 の両方で利用可能

チャートのソース

アップグレードまたはインストール

値

チャートの依存関係

Python パッケージ

インストール

サーバーとしての使用

クライアントとしての使用

CLI

FastMCP との統合

バイナリの検出

環境変数

レジリエンス設定（Python）

環境変数

CLI フラグ

プログラムによる設定

OpenTelemetry

レスポンスペイロードの管理

レスポンスの切り詰め

マニフェストのサニタイズ

レジリエンスの基本機能

既知の制限事項

プラグインツールは Helm CLI を使用します

セキュリティ

プロセスの強化（Linux）

評価したが実装しなかった仕組み

認証情報のマスキング

入力の検証

ファイル権限

HTTP サーバーの強化

認証（OIDC/OAuth2）

クイックスタート — Entra ID（Azure AD / ADFS）

環境変数

認証の優先順位

待機：`wait` と `wait_strategy`