Complete Guide to MCP Kubernetes Server Environment Variables

The MCP Kubernetes server exposes over 30 environment variables that control network binding, DNS rebinding protection, Kubernetes authentication, tool safety restrictions, and OpenTelemetry observability.

The flux159/mcp-server-kubernetes repository implements a Model Context Protocol (MCP) server that enables AI assistants to interact with Kubernetes clusters. Rather than relying on configuration files, the server uses a comprehensive environment variable interface for all runtime behavior, making it ideal for containerized deployments where volume mounts are undesirable.

Server Networking and DNS Protection

The HTTP transport layer reads networking parameters from src/utils/streamable-http.ts to determine how the server binds to the network.

• PORT – TCP port the HTTP server listens on. Defaults to 3000 when unset. Referenced in src/utils/streamable-http.ts at lines 112‑119.
• HOST – Hostname or IP address for the server binding. Defaults to localhost. Defined in src/utils/streamable-http.ts at lines 119‑120.

To prevent DNS rebinding attacks, the server implements strict host-header validation:

• DNS_REBINDING_PROTECTION – When set to "true", enables strict host-header checking to block DNS rebinding attempts. Implemented in src/utils/streamable-http.ts at lines 23‑25.
• DNS_REBINDING_ALLOWED_HOST – Comma-separated list of additional hostnames that bypass rebinding protection. Parsed in src/utils/streamable-http.ts at lines 24‑25.

Kubernetes Connection Configuration

The KubernetesManager class in src/utils/kubernetes-manager.ts supports multiple authentication strategies controlled by environment variables.

Kubeconfig File Methods

When a physical kubeconfig file is available:

• KUBECONFIG – Standard path to a kubeconfig file used by kubectl CLI conventions. Checked at lines 69‑71.
• KUBECONFIG_PATH – Custom location that overrides KUBECONFIG when specified. Evaluated at lines 221‑226.
• K8S_CONTEXT – Name of the context to activate on startup. The manager switches to this context during initialization at lines 86‑89.

For inline configuration without a file:

• KUBECONFIG_YAML – Raw kubeconfig YAML string written to a temporary file at startup. Processed at lines 25‑27.
• KUBECONFIG_JSON – Kubeconfig expressed as JSON, parsed and persisted to a temp file. Handled at lines 130‑172.

Static Configuration (No Kubeconfig)

For direct API server authentication without any kubeconfig:

• K8S_SERVER – Direct URL to the Kubernetes API server (e.g., https://my-k8s.example.com). Referenced at lines 140‑142.
• K8S_TOKEN – Bearer token for API server authentication. Used in conjunction with K8S_SERVER at lines 140‑197.
• K8S_CA_DATA – Base64-encoded CA certificate for TLS verification. Parsed at lines 186‑192.
• K8S_SKIP_TLS_VERIFY – When set to "true" and no K8S_CA_DATA is provided, TLS verification is disabled. Checked at lines 185‑186.

Namespace Defaults

• K8S_NAMESPACE – Default namespace for operations when none is specified in requests. Falls back to "default" if unset. Defined at lines 337‑339.

Authentication and Security

The server implements token-based authentication and secret masking controlled by environment variables.

• MCP_AUTH_TOKEN – Bearer token protecting the MCP HTTP endpoint. When set, all incoming requests must include this token in the Authorization header. Implemented in src/utils/auth.ts at lines 17‑23.

• MASK_SECRETS – Controls redaction of sensitive data in kubectl get output. When not set to "false", secret values are replaced with "*****". Evaluated in src/tools/kubectl-get.ts at lines 166‑168.

Tool Filtering and Safety Modes

The entry point in src/index.ts evaluates safety flags to restrict available tools.

• ALLOW_ONLY_READONLY_TOOLS – When set to "true", exposes only read-only tools (e.g., kubectl-get, kubectl-describe). Evaluated at lines 80‑82.

• ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS – When set to "true", hides destructive tools such as delete and apply operations. Checked at lines 81‑83.

• ALLOWED_TOOLS – Comma-separated whitelist of specific tool names to expose. Overrides the broader read-only and non-destructive flags. Parsed at lines 81‑83.

Transport Protocol Toggles

Experimental transport mechanisms can be enabled via feature flags in src/index.ts.

• ENABLE_UNSAFE_SSE_TRANSPORT – Enables Server-Sent Events transport. Marked as experimental and potentially unsafe. Referenced at lines 554‑556.

• ENABLE_UNSAFE_STREAMABLE_HTTP_TRANSPORT – Enables streaming HTTP transport. Also experimental and potentially unsafe. Referenced at lines 557‑559.

OpenTelemetry Telemetry Configuration

The telemetry subsystem in src/config/telemetry-config.ts supports comprehensive OpenTelemetry configuration.

• ENABLE_TELEMETRY – Master switch for OpenTelemetry tracing. Set to "true" to enable. Evaluated at lines 78‑82.

• OTEL_EXPORTER_OTLP_ENDPOINT – Destination URL for OTLP traces (e.g., http://localhost:4317 for Jaeger). Configured at lines 81‑84.

• OTEL_SERVICE_NAME – Logical service name reported to telemetry backends. Defined at lines 95‑96.

• OTEL_SERVICE_VERSION – Service version string for telemetry. Defined at lines 95‑96.

• OTEL_TRACES_SAMPLER – Sampling strategy (always_on, always_off, traceidratio). Configured at lines 31‑33.

• OTEL_TRACES_SAMPLER_ARG – Argument for the sampler (e.g., sampling ratio 0.5). Configured at lines 31‑34.

• OTEL_RESOURCE_ATTRIBUTES – Additional resource attributes as comma-separated key=value pairs. Parsed at lines 58‑60.

• OTEL_CAPTURE_RESPONSE_METADATA – When "true", captures HTTP response metadata for traces. Evaluated at lines 89‑90.

Runtime Limits

Child process execution limits are controlled via:

• SPAWN_MAX_BUFFER – Maximum buffer size in bytes for child process stdio. Defaults to 1048577. Defined in src/config/max-buffer.ts at lines 2‑3.

Practical Configuration Examples

Running the Server on a Custom Port and Host

PORT=8080 HOST=0.0.0.0 bun run start

The server listens on http://0.0.0.0:8080 instead of the default localhost:3000.

Providing a Static Kubernetes Configuration

When running without a kubeconfig file, provide connection details directly:

K8S_SERVER=https://my-k8s.example.com \
K8S_TOKEN=abcdef123456 \
K8S_CA_DATA=$(cat ca.crt | base64) \
K8S_NAMESPACE=production \
bun run start

The KubernetesManager constructs an in-memory kubeconfig from these values at startup.

Enabling OpenTelemetry with Jaeger

ENABLE_TELEMETRY=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_SERVICE_NAME=mcp-k8s \
OTEL_TRACES_SAMPLER=always_on \
bun run start

Traces export to the OTLP endpoint configured in src/config/telemetry-config.ts.

Restricting Tools to Read-Only Operations

ALLOW_ONLY_READONLY_TOOLS=true bun run start

The server exposes only non-destructive tools such as kubectl-get and kubectl-describe, filtering the tool list in src/index.ts.

Controlling Secret Masking

# Default behavior: mask secrets

MASK_SECRETS=true bun run start

# To view raw secret values (use with caution)

MASK_SECRETS=false bun run start

When enabled, src/tools/kubectl-get.ts replaces secret data fields with "*****".

Summary

• Network binding is controlled via PORT and HOST, with DNS_REBINDING_PROTECTION providing security against DNS rebinding attacks.
• Kubernetes authentication supports multiple strategies: standard kubeconfig files (KUBECONFIG), inline YAML/JSON (KUBECONFIG_YAML, KUBECONFIG_JSON), or static tokens (K8S_TOKEN, K8S_SERVER).
• Security features include bearer token authentication (MCP_AUTH_TOKEN), secret masking (MASK_SECRETS), and granular tool filtering (ALLOW_ONLY_READONLY_TOOLS, ALLOWED_TOOLS).
• Observability integrates with OpenTelemetry through the OTEL_* family of variables, configurable via src/config/telemetry-config.ts.
• Runtime tuning includes child process buffer limits (SPAWN_MAX_BUFFER) and experimental transport toggles.

Frequently Asked Questions

How do I configure the MCP Kubernetes server to use a specific kubeconfig file?

Set the KUBECONFIG_PATH environment variable to the absolute path of your configuration file. This variable overrides the standard KUBECONFIG location and is processed in src/utils/kubernetes-manager.ts at lines 221‑226. If you need to switch contexts within that file, also set K8S_CONTEXT to the desired context name.

What is the difference between ALLOW_ONLY_READONLY_TOOLS and ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS?

ALLOW_ONLY_READONLY_TOOLS restricts the server to tools that only read cluster state, such as kubectl-get and kubectl-describe, as evaluated in src/index.ts at lines 80‑82. ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS is slightly broader, hiding tools that delete or modify resources while potentially allowing apply operations that create new resources. Both flags are superseded by the ALLOWED_TOOLS variable, which accepts a comma-separated whitelist of specific tool names.

How do I enable OpenTelemetry tracing with a custom sampling rate?

Set ENABLE_TELEMETRY=true to activate the telemetry subsystem defined in src/config/telemetry-config.ts. Configure the sampling strategy using OTEL_TRACES_SAMPLER=traceidratio and set the ratio via OTEL_TRACES_SAMPLER_ARG=0.1 to sample 10% of traces. Point the exporter to your collector with OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317.

Is it possible to run the server without a kubeconfig file on disk?

Yes. Provide a static configuration using the K8S_SERVER, K8S_TOKEN, and optionally K8S_CA_DATA environment variables. The KubernetesManager in src/utils/kubernetes-manager.ts constructs an in-memory kubeconfig from these values at lines 140‑197. You can also pass a complete kubeconfig as a string using KUBECONFIG_YAML or KUBECONFIG_JSON, which the server writes to a temporary file at startup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}