Kubernetes Resources Reference

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 req/h に引き上げられます。複数のバージョンを読み込む場合に推奨されます。
キーストア	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 transport を実装しています。エンドポイントは次のとおりです。

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	キーのティアのレート制限を超過

不明なツール名、必須引数の不足、kind が見つからないなどの MCP レベルのエラーは、通常の 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 ランタイムで、シェルやパッケージマネージャーは含まれていません。