kubernetools MCP Server

kubernetools/mcp-server

kubernetools MCP サーバーのコンテナイメージです。

レジストリ: ghcr.io/kubernetools/mcp-server

クイックスタート

匿名モード (ローカル利用)

認証は不要です。すべての接続は送信元 IP ごとに無料ティアの制限でレート制限されます。

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  ghcr.io/kubernetools/mcp-server:latest

API キー認証を使用する場合

# 1. Create a key store file
echo '[{"key":"mykey","tier":"free"}]' > keys.json

# 2. Start the server
podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.33,v1.34,v1.35,v1.36 \
  -e KEY_STORE_PATH=/keys.json \
  ghcr.io/kubernetools/mcp-server:latest

設定

パラメータ	環境変数	説明
Kubernetes バージョン	K8S_VERSIONS	プリロードするバージョンのカンマ区切りリスト (例: v1.33,v1.34)。デフォルトは v1.33 です。
GitHub トークン	GITHUB_TOKEN	パーソナルアクセストークン (追加スコープ不要)。オプション。GitHub API のレート制限を 60 回/時から 5,000 回/時に引き上げます。複数バージョンをロードする場合に推奨されます。
キーストア	KEY_STORE_PATH	API キー JSON ファイルへのパス (コンテナにマウントしてください)。省略すると、サーバーは匿名モードで実行されます。認証は不要で、すべての接続は送信元 IP ごとに無料ティアの制限でレート制限されます。
許可されたホスト	ALLOWED_HOSTS	受け入れる Host ヘッダー値のカンマ区切りリスト (例: mcp.example.com,mcp.example.com:443)。省略すると、ホスト検証は無効になります。これはローカル開発にのみ適しています。DNS リバインディング攻撃を防ぐため、本番環境では常に設定してください。
ブラウザリダイレクト	BROWSER_REDIRECT_URL	プレーンなブラウザの GET リクエストをリダイレクトする URL。MCP クライアントは Accept: text/event-stream で検出され、ブラウザは代わりにこの URL へ 307 を受け取ります。省略すると、ブラウザの GET は 400 を返します。
ログレベル	RUST_LOG	ログレベルフィルタ (例: info、debug、mcp=debug)。
ポート	--publish	サーバーはポート 3000 でリッスンします。

認証

API キーストア

キーストアは、起動時に一度だけロードされるフラットな JSON 配列です。

[
  { "key": "free-key-abc", "tier": "free" },
  { "key": "paid-key-xyz", "tier": "paid" }
]

すべてのリクエストには、Authorization ヘッダーにキーを含める必要があります。

Authorization: Bearer free-key-abc

有効なキーがないリクエストは 401 Unauthorized を受け取ります。

匿名モード

KEY_STORE_PATH が設定されていない場合、サーバーは認証なしで実行されます。すべての接続が受け入れられ、送信元 IP ごとに無料ティアの制限でレート制限されます。ローカルでの利用に便利ですが、公開しないでください。

ティアとレート制限

ティア	制限
free	10 リクエスト/分、バースト 10
paid	約 1,000 リクエスト/秒、バースト 1,000 (実質的に無制限)

制限を超えたリクエストは 429 Too Many Requests を受け取ります。制限は IP ごとではなく、API キーごとに追跡されます。

MCP クライアントの接続

サーバーは MCP Streamable HTTP トランスポート を実装しています。エンドポイントは次のとおりです。

http://<host>:<port>/[?version=<k8s-version>]

version クエリパラメータで、セッションに使用する Kubernetes バージョンを選択します。省略すると、最初にロードされたバージョンが使用されます。不明なバージョンは 400 Bad Request を返します。

Claude Desktop

claude_desktop_config.json に以下を追加してください。

{
  "mcpServers": {
    "kubernetools": {
      "url": "http://localhost:3000/?version=v1.36",
      "headers": {
        "Authorization": "Bearer mykey"
      }
    }
  }
}

利用可能なツール

list_resources

軽量な検出 — リソースごとに 1 エントリを返し、(group, kind, api_version) でソートされます。kind 名を見つけるために最初に使用してください。

オプションのフィルタ: group (例: "apps"、"core")、api_version (例: "v1")。

get_resource

完全なリソース詳細 — フィールド、spec、status、リストフィールド — 1 回の呼び出しでマニフェストを作成するのに十分な情報です。必須: kind。オプション: group、api_version (デフォルトは最新)。

null 以外の type_ref と空の sub_fields を持つフィールドは、get_type で掘り下げる必要があります。

get_type

get_resource 出力の type_ref を介して参照される単一の複合型を掘り下げます。必須: type_name (例: "Container"、"PodFailurePolicy")。

典型的なクエリフロー

list_resources                          → discover kind names and groups
  └─ get_resource(kind="Deployment")   → see all top-level fields + spec/status
       └─ get_type(type_name="...")    → drill into any complex type_ref

ヘルスチェック

ポート 3000 で GET /healthz。

• Kubernetes API ドキュメントのロード中は 503 Service Unavailable (ボディ: loading) を返します。
• サーバーの準備が完了すると 200 OK (ボディ: ok) を返します。

このエンドポイントは認証とレート制限をバイパスします。

起動、準備状況、および生存プローブに使用します。

startupProbe:
  httpGet:
    path: /healthz
    port: 3000
  failureThreshold: 30   # allow up to 5 min for version loading
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthz
    port: 3000
livenessProbe:
  httpGet:
    path: /healthz
    port: 3000
  initialDelaySeconds: 10

エラーレスポンス

HTTP ステータス	原因
307 Temporary Redirect	BROWSER_REDIRECT_URL が設定されている場合のブラウザ GET
400 Bad Request	BROWSER_REDIRECT_URL が設定されていない場合のブラウザ GET、または version パラメータが起動時にロードされていないバージョンを指定している場合
401 Unauthorized	Authorization: Bearer <key> ヘッダーがないか無効
429 Too Many Requests	キーのティアのレート制限を超過

MCP レベルのエラー (不明なツール名、必須引数の欠落、kind が見つからない) は、通常の 200 レスポンス内の MCP エラーコンテンツとして返されます。

例

複数の Kubernetes バージョン

podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.33,v1.34,v1.35,v1.36 \
  -e GITHUB_TOKEN=ghp_... \
  -e KEY_STORE_PATH=/keys.json \
  ghcr.io/kubernetools/mcp-server:latest

ホスト検証を使用した本番環境セットアップ

podman run -d \
  -p 3000:3000 \
  -v "$(pwd)/keys.json:/keys.json:ro" \
  -e K8S_VERSIONS=v1.36 \
  -e KEY_STORE_PATH=/keys.json \
  -e ALLOWED_HOSTS=mcp.example.com,mcp.example.com:443 \
  -e BROWSER_REDIRECT_URL=https://example.com/docs \
  ghcr.io/kubernetools/mcp-server:latest

デバッグログ

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  -e RUST_LOG=debug \
  ghcr.io/kubernetools/mcp-server:latest

特定のリリースに固定

podman run -d \
  -p 3000:3000 \
  -e K8S_VERSIONS=v1.33 \
  ghcr.io/kubernetools/mcp-server:0.1.0

イメージ

registry.access.redhat.com/hi/core-runtime:2.42-openssl 上に構築 — 最小限の distroless glibc + OpenSSL ランタイム。シェルやパッケージマネージャは含まれていません。