Kubernetes Resources Reference

Help AI agents write accurate, up-to-date Kubernetes manifests by giving them the official Kubernetes API reference, so they can look up kinds, fields, and nested types with current specs across the latest and three previous Kubernetes versions

- Discover available Kubernetes resource kinds— ask the AI to calllist_resourcesto see all resource types, optionally filtered by API group or version.
- Get the full schema for a resource— useget_resourceto retrieve every field, spec, and status detail needed to write a manifest for a given kind.
- Drill into nested type definitions— when a field references a complex type, callget_typeby name to expand its structure and sub-fields.
- Target a specific Kubernetes version— connect with aversionquery parameter to work against the API schema of a particular release like v1.36.

Container image for thekubernetoolsMCP server.

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

# 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

The key store is a flat JSON array loaded once at startup:

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

Every request must include the key in theAuthorizationheader:

Requests without a valid key receive401 Unauthorized.

WhenKEY_STORE_PATHis not set, the server runs without authentication. All connections are accepted and rate-limited per source IP at the free-tier limit. Convenient for local use; do not expose publicly.

Requests that exceed the limit receive429 Too Many Requests. Limits are tracked per API key, not per IP.

The server implements theMCP Streamable HTTP transport. The endpoint is:

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

Theversionquery parameter selects which Kubernetes version to use for the session. If omitted, the first loaded version is used. An unknown version returns400 Bad Request.

Add the following toclaude_desktop_config.json:

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

Lightweight discovery — returns one entry per resource, sorted by(group, kind, api_version). Use this first to find kind names.

Optional filters:group(e.g."apps","core"),api_version(e.g."v1").

Full resource detail — fields, spec, status, and list fields — enough to write a manifest in one call. Required:kind. Optional:group,api_version(defaults to most recent).

Fields with a non-nulltype_refand emptysub_fieldsshould be drilled into withget_type.

Drill into a single composite type referenced viatype_refinget_resourceoutput. Required:type_name(e.g."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

- Returns503 Service Unavailable(body:loading) while Kubernetes API docs are loading.
- Returns200 OK(body:ok) once the server is ready.

This endpoint bypasses authentication and rate limiting.

Use it for startup, readiness, and liveness probes:

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

MCP-level errors (unknown tool name, missing required argument, kind not found) are returned as MCP error content inside a normal200response.

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

Built onregistry.access.redhat.com/hi/core-runtime:2.42-openssl— a minimal, distroless glibc + OpenSSL runtime. No shell or package manager.

Run and interpret Kubernetes commands interactively with a provided kubeconfig.