kubernetools MCP Server

kubernetools/mcp-server

Imagem de contêiner para o servidor MCP kubernetools.

Registro: ghcr.io/kubernetools/mcp-server

Início rápido

Modo anônimo (uso local)

Nenhuma autenticação necessária; todas as conexões são limitadas por taxa por IP de origem no limite do nível gratuito.

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

Com autenticação por chave de 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

Configuração

Parâmetro	Variável de ambiente	Descrição
Versões do Kubernetes	K8S_VERSIONS	Lista separada por vírgulas de versões para pré-carregar (ex.: v1.33,v1.34). O padrão é v1.33.
Token do GitHub	GITHUB_TOKEN	Token de acesso pessoal (sem escopos extras necessários). Opcional; aumenta o limite de taxa da API do GitHub de 60 para 5.000 req/h — recomendado ao carregar várias versões.
Armazenamento de chaves	KEY_STORE_PATH	Caminho para o arquivo JSON de chaves de API (monte-o no contêiner). Quando omitido, o servidor executa em modo anônimo: nenhuma autenticação é necessária e todas as conexões são limitadas por taxa por IP de origem no limite do nível gratuito.
Hosts permitidos	ALLOWED_HOSTS	Valores de cabeçalho Host separados por vírgulas para aceitar (ex.: mcp.example.com,mcp.example.com:443). Quando omitido, a validação de host é desabilitada — adequado apenas para desenvolvimento local. Sempre defina isso em produção para prevenir ataques de rebinding de DNS.
Redirecionamento do navegador	BROWSER_REDIRECT_URL	URL para redirecionar requisições GET simples do navegador. Clientes MCP são detectados por Accept: text/event-stream; navegadores recebem 307 para esta URL em vez disso. Quando omitido, GETs do navegador retornam 400.
Nível de log	RUST_LOG	Filtro de nível de log (ex.: info, debug, mcp=debug).
Porta	--publish	O servidor escuta na porta 3000.

Autenticação

Armazenamento de chaves de API

O armazenamento de chaves é um array JSON simples carregado uma vez na inicialização:

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

Toda requisição deve incluir a chave no cabeçalho Authorization:

Authorization: Bearer free-key-abc

Requisições sem uma chave válida recebem 401 Unauthorized.

Modo anônimo

Quando KEY_STORE_PATH não está definido, o servidor executa sem autenticação. Todas as conexões são aceitas e limitadas por taxa por IP de origem no limite do nível gratuito. Conveniente para uso local; não exponha publicamente.

Níveis e limites de taxa

Nível	Limite
free	10 requisições / minuto, rajada 10
paid	~1.000 requisições / segundo, rajada 1.000 (efetivamente ilimitado)

Requisições que excedem o limite recebem 429 Too Many Requests. Os limites são rastreados por chave de API, não por IP.

Conectando um cliente MCP

O servidor implementa o Transporte HTTP Transmissível MCP. O endpoint é:

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

O parâmetro de consulta version seleciona qual versão do Kubernetes usar para a sessão. Se omitido, a primeira versão carregada é usada. Uma versão desconhecida retorna 400 Bad Request.

Claude Desktop

Adicione o seguinte ao claude_desktop_config.json:

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

Ferramentas disponíveis

list_resources

Descoberta leve — retorna uma entrada por recurso, ordenada por (group, kind, api_version). Use isso primeiro para encontrar nomes de tipos.

Filtros opcionais: group (ex.: "apps", "core"), api_version (ex.: "v1").

get_resource

Detalhe completo do recurso — campos, spec, status e campos de lista — suficiente para escrever um manifesto em uma chamada. Obrigatório: kind. Opcional: group, api_version (padrão para o mais recente).

Campos com um type_ref não nulo e sub_fields vazio devem ser aprofundados com get_type.

get_type

Aprofunde em um único tipo composto referenciado via type_ref na saída de get_resource. Obrigatório: type_name (ex.: "Container", "PodFailurePolicy").

Fluxo de consulta típico

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

Verificação de saúde

GET /healthz na porta 3000.

• Retorna 503 Service Unavailable (corpo: loading) enquanto a documentação da API do Kubernetes está carregando.
• Retorna 200 OK (corpo: ok) assim que o servidor estiver pronto.

Este endpoint ignora autenticação e limitação de taxa.

Use-o para sondas de inicialização, prontidão e vivacidade:

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

Respostas de erro

Status HTTP	Causa
307 Temporary Redirect	GET do navegador quando BROWSER_REDIRECT_URL está definido
400 Bad Request	GET do navegador quando BROWSER_REDIRECT_URL não está definido, ou o parâmetro version nomeia uma versão não carregada na inicialização
401 Unauthorized	Cabeçalho Authorization: Bearer <key> ausente ou inválido
429 Too Many Requests	Limite de taxa excedido para o nível da chave

Erros de nível MCP (nome de ferramenta desconhecido, argumento obrigatório ausente, tipo não encontrado) são retornados como conteúdo de erro MCP dentro de uma resposta 200 normal.

Exemplos

Múltiplas versões do 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

Configuração de produção com validação de 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 de depuração

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

Fixar em uma versão específica

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

Imagem

Construída sobre registry.access.redhat.com/hi/core-runtime:2.42-openssl — um runtime mínimo, distroless glibc + OpenSSL. Sem shell ou gerenciador de pacotes.