# Complete Guide to MCP Kubernetes Server Environment Variables

> Discover over 30 MCP Kubernetes server environment variables to configure network binding, DNS protection, authentication, tool safety, and OpenTelemetry. Optimize your server behavior today.

- Repository: [Suyog Sonwalkar/mcp-server-kubernetes](https://github.com/flux159/mcp-server-kubernetes)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/streamable-http.ts) at lines 24‑25.

## Kubernetes Connection Configuration

The `KubernetesManager` class in [`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-get.ts) at lines 166‑168.

## Tool Filtering and Safety Modes

The entry point in [`src/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/max-buffer.ts) at lines 2‑3.

## Practical Configuration Examples

### Running the Server on a Custom Port and Host

```bash
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:

```bash
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

```bash
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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/telemetry-config.ts).

### Restricting Tools to Read-Only Operations

```bash
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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts).

### Controlling Secret Masking

```bash

# 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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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`](https://github.com/flux159/mcp-server-kubernetes/blob/main/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.