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 偵測；瀏覽器則會收到 307 並重新導向至此 URL。省略時，瀏覽器 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。限制是按 API 金鑰追蹤，而非按 IP。

連線 MCP 用戶端

伺服器實作了 MCP 可串流 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

輕量級探索 — 每個資源傳回一個條目，按 (group, kind, api_version) 排序。先使用此工具來尋找類型名稱。

選用篩選器： group（例如 "apps"、"core"）、api_version（例如 "v1"）。

get_resource

完整資源詳細資料 — 欄位、規格、狀態和清單欄位 — 足以在一次呼叫中編寫清單。必要項：kind。選用項：group、api_version（預設為最新版本）。

具有非空 type_ref 和空 sub_fields 的欄位，應使用 get_type 向下鑽研。

get_type

向下鑽研至透過 type_ref 在 get_resource 輸出中參考的單一複合類型。必要項：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

健康檢查

GET /healthz 在連接埠 3000 上。

• 在 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 層級錯誤（未知的工具名稱、缺少必要引數、找不到類型）會作為 MCP 錯誤內容，在正常的 200 回應中傳回。

範例

多個 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 之上 — 一個最小化、無發行版的 glibc + OpenSSL 執行階段。沒有殼層或套件管理器。