kubernetools MCP Server

kubernetools/mcp-server

kubernetools MCP sunucusu için konteyner imajı.

Kayıt Defteri: ghcr.io/kubernetools/mcp-server

Hızlı başlangıç

Anonim mod (yerel kullanım)

Kimlik doğrulama gerekmez; tüm bağlantılar, ücretsiz katman sınırında kaynak IP başına hız sınırlandırmasına tabidir.

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

API anahtarı kimlik doğrulaması ile

# 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

Yapılandırma

Parametre	Ortam değişkeni	Açıklama
Kubernetes sürümleri	K8S_VERSIONS	Önceden yüklenecek sürümlerin virgülle ayrılmış listesi (örn. v1.33,v1.34). Varsayılan: v1.33.
GitHub token'ı	GITHUB_TOKEN	Kişisel erişim token'ı (ekstra kapsam gerekmez). İsteğe bağlı; GitHub API hız sınırını 60'tan 5.000 istek/saat'e yükseltir — birden fazla sürüm yüklerken önerilir.
Anahtar deposu	KEY_STORE_PATH	API anahtarı JSON dosyasının yolu (konteynere bağlayın). Atlanırsa, sunucu anonim modda çalışır: kimlik doğrulama gerekmez ve tüm bağlantılar ücretsiz katman sınırında kaynak IP başına hız sınırlandırmasına tabidir.
İzin verilen ana bilgisayarlar	ALLOWED_HOSTS	Kabul edilecek Host başlık değerlerinin virgülle ayrılmış listesi (örn. mcp.example.com,mcp.example.com:443). Atlanırsa, ana bilgisayar doğrulaması devre dışı bırakılır — yalnızca yerel geliştirme için uygundur. DNS yeniden bağlama saldırılarını önlemek için üretimde her zaman ayarlayın.
Tarayıcı yönlendirmesi	BROWSER_REDIRECT_URL	Düz tarayıcı GET isteklerinin yönlendirileceği URL. MCP istemcileri Accept: text/event-stream ile algılanır; tarayıcılar bunun yerine bu URL'ye 307 alır. Atlanırsa, tarayıcı GET'leri 400 döndürür.
Günlük seviyesi	RUST_LOG	Günlük seviyesi filtresi (örn. info, debug, mcp=debug).
Port	--publish	Sunucu 3000 portunu dinler.

Kimlik doğrulama

API anahtar deposu

Anahtar deposu, başlangıçta bir kez yüklenen düz bir JSON dizisidir:

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

Her istek, anahtarı Authorization başlığında içermelidir:

Authorization: Bearer free-key-abc

Geçerli bir anahtar içermeyen istekler 401 Unauthorized alır.

Anonim mod

KEY_STORE_PATH ayarlanmadığında, sunucu kimlik doğrulama olmadan çalışır. Tüm bağlantılar kabul edilir ve ücretsiz katman sınırında kaynak IP başına hız sınırlandırmasına tabidir. Yerel kullanım için uygundur; herkese açık olarak yayınlamayın.

Katmanlar ve hız sınırları

Katman	Sınır
free	10 istek / dakika, ani 10
paid	~1.000 istek / saniye, ani 1.000 (pratikte sınırsız)

Sınırı aşan istekler 429 Too Many Requests alır. Sınırlar, IP başına değil, API anahtarı başına izlenir.

Bir MCP istemcisi bağlama

Sunucu, MCP Akışlı HTTP aktarımını uygular. Uç nokta:

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

version sorgu parametresi, oturum için hangi Kubernetes sürümünün kullanılacağını seçer. Atlanırsa, yüklenen ilk sürüm kullanılır. Bilinmeyen bir sürüm 400 Bad Request döndürür.

Claude Desktop

claude_desktop_config.json dosyasına aşağıdakini ekleyin:

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

Kullanılabilir araçlar

list_resources

Hafif keşif — kaynak başına bir giriş döndürür, (group, kind, api_version)'e göre sıralanır. Tür adlarını bulmak için önce bunu kullanın.

İsteğe bağlı filtreler: group (örn. "apps", "core"), api_version (örn. "v1").

get_resource

Tam kaynak detayı — alanlar, spec, status ve liste alanları — tek bir çağrıda bir manifest yazmak için yeterlidir. Gerekli: kind. İsteğe bağlı: group, api_version (varsayılan en son sürümdür).

Boş olmayan type_ref ve boş sub_fields içeren alanlar, get_type ile detaylandırılmalıdır.

get_type

get_resource çıktısında type_ref aracılığıyla başvurulan tek bir bileşik türü detaylandırır. Gerekli: type_name (örn. "Container", "PodFailurePolicy").

Tipik sorgu akışı

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

Sağlık kontrolü

3000 portunda GET /healthz.

• Kubernetes API belgeleri yüklenirken 503 Service Unavailable (gövde: loading) döndürür.
• Sunucu hazır olduğunda 200 OK (gövde: ok) döndürür.

Bu uç nokta, kimlik doğrulama ve hız sınırlandırmasını atlar.

Başlatma, hazır olma ve canlılık sondaları için kullanın:

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

Hata yanıtları

HTTP durumu	Neden
307 Temporary Redirect	BROWSER_REDIRECT_URL ayarlandığında tarayıcı GET'i
400 Bad Request	BROWSER_REDIRECT_URL ayarlanmadığında tarayıcı GET'i veya version parametresi başlangıçta yüklenmemiş bir sürümü adlandırdığında
401 Unauthorized	Eksik veya geçersiz Authorization: Bearer <key> başlığı
429 Too Many Requests	Anahtarın katmanı için hız sınırı aşıldı

MCP düzeyindeki hatalar (bilinmeyen araç adı, eksik gerekli argüman, tür bulunamadı), normal bir 200 yanıtı içinde MCP hata içeriği olarak döndürülür.

Örnekler

Birden fazla Kubernetes sürümü

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

Ana bilgisayar doğrulamalı üretim kurulumu

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

Hata ayıklama günlüğü

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

Belirli bir sürüme sabitleme

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

İmaj

registry.access.redhat.com/hi/core-runtime:2.42-openssl üzerine inşa edilmiştir — minimal, dağıtımsız bir glibc + OpenSSL çalışma zamanı. Kabuk veya paket yöneticisi yoktur.