kubernetools MCP Server

kubernetools/mcp-server

Image kontainer untuk server MCP kubernetools.

Registry: ghcr.io/kubernetools/mcp-server

Mulai cepat

Mode anonim (penggunaan lokal)

Tidak diperlukan autentikasi; semua koneksi dibatasi laju per IP sumber pada batas tingkat gratis.

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

Dengan autentikasi kunci 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

Konfigurasi

Parameter	Var lingkungan	Deskripsi
Versi Kubernetes	K8S_VERSIONS	Daftar versi yang dipisahkan koma untuk dimuat sebelumnya (mis. v1.33,v1.34). Default ke v1.33.
Token GitHub	GITHUB_TOKEN	Token akses pribadi (tidak perlu cakupan tambahan). Opsional; menaikkan batas laju API GitHub dari 60 menjadi 5.000 req/jam — disarankan saat memuat banyak versi.
Penyimpanan kunci	KEY_STORE_PATH	Jalur ke berkas JSON kunci API (pasang ke dalam kontainer). Jika dihilangkan, server berjalan dalam mode anonim: tidak diperlukan autentikasi dan semua koneksi dibatasi laju per IP sumber pada batas tingkat gratis.
Host yang diizinkan	ALLOWED_HOSTS	Nilai header Host yang dipisahkan koma untuk diterima (mis. mcp.example.com,mcp.example.com:443). Jika dihilangkan, validasi host dinonaktifkan — hanya cocok untuk pengembangan lokal. Selalu atur ini di produksi untuk mencegah serangan DNS-rebinding.
Pengalihan peramban	BROWSER_REDIRECT_URL	URL untuk mengalihkan permintaan GET peramban biasa. Klien MCP terdeteksi oleh Accept: text/event-stream; peramban menerima 307 ke URL ini sebagai gantinya. Jika dihilangkan, GET peramban mengembalikan 400.
Tingkat log	RUST_LOG	Filter tingkat log (mis. info, debug, mcp=debug).
Port	--publish	Server mendengarkan pada port 3000.

Autentikasi

Penyimpanan kunci API

Penyimpanan kunci adalah array JSON datar yang dimuat sekali saat startup:

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

Setiap permintaan harus menyertakan kunci di header Authorization:

Authorization: Bearer free-key-abc

Permintaan tanpa kunci yang valid menerima 401 Unauthorized.

Mode anonim

Saat KEY_STORE_PATH tidak diatur, server berjalan tanpa autentikasi. Semua koneksi diterima dan dibatasi laju per IP sumber pada batas tingkat gratis. Nyaman untuk penggunaan lokal; jangan diekspos secara publik.

Tingkatan dan batas laju

Tingkatan	Batas
free	10 permintaan / menit, burst 10
paid	~1.000 permintaan / detik, burst 1.000 (secara efektif tidak terbatas)

Permintaan yang melebihi batas menerima 429 Too Many Requests. Batas dilacak per kunci API, bukan per IP.

Menghubungkan klien MCP

Server mengimplementasikan Transport HTTP Streamable MCP. Endpoint-nya adalah:

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

Parameter kueri version memilih versi Kubernetes yang akan digunakan untuk sesi. Jika dihilangkan, versi pertama yang dimuat akan digunakan. Versi yang tidak dikenal mengembalikan 400 Bad Request.

Claude Desktop

Tambahkan berikut ini ke claude_desktop_config.json:

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

Alat yang tersedia

list_resources

Penemuan ringan — mengembalikan satu entri per sumber daya, diurutkan berdasarkan (group, kind, api_version). Gunakan ini terlebih dahulu untuk menemukan nama jenis.

Filter opsional: group (mis. "apps", "core"), api_version (mis. "v1").

get_resource

Detail sumber daya lengkap — field, spec, status, dan field daftar — cukup untuk menulis manifes dalam satu panggilan. Diperlukan: kind. Opsional: group, api_version (default ke yang terbaru).

Field dengan type_ref non-null dan sub_fields kosong harus ditelusuri lebih dalam dengan get_type.

get_type

Telusuri lebih dalam satu tipe komposit yang direferensikan melalui type_ref dalam output get_resource. Diperlukan: type_name (mis. "Container", "PodFailurePolicy").

Alur kueri umum

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

Pemeriksaan kesehatan

GET /healthz pada port 3000.

• Mengembalikan 503 Service Unavailable (body: loading) saat dokumen API Kubernetes sedang dimuat.
• Mengembalikan 200 OK (body: ok) setelah server siap.

Endpoint ini melewati autentikasi dan pembatasan laju.

Gunakan untuk probe startup, readiness, dan liveness:

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

Respons kesalahan

Status HTTP	Penyebab
307 Temporary Redirect	GET peramban saat BROWSER_REDIRECT_URL diatur
400 Bad Request	GET peramban saat BROWSER_REDIRECT_URL tidak diatur, atau parameter version menyebutkan versi yang tidak dimuat saat startup
401 Unauthorized	Header Authorization: Bearer <key> hilang atau tidak valid
429 Too Many Requests	Batas laju terlampaui untuk tingkatan kunci

Kesalahan tingkat MCP (nama alat tidak dikenal, argumen wajib hilang, jenis tidak ditemukan) dikembalikan sebagai konten kesalahan MCP di dalam respons 200 normal.

Contoh

Beberapa versi 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

Pengaturan produksi dengan validasi host

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

Log debug

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

Sematkan ke rilis tertentu

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

Image

Dibangun di atas registry.access.redhat.com/hi/core-runtime:2.42-openssl — runtime glibc + OpenSSL minimal dan distroless. Tanpa shell atau manajer paket.