Advanced README for mcp-server-kubernetes

Large clusters

If you have large clusters or see a spawnSync ENOBFUS error, you may need to specify the environment argument SPAWN_MAX_BUFFER (in bytes) when running the server. See this issue for more information.

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "SPAWN_MAX_BUFFER": "5242880" // 5MB = 1024*1024*5. Default is 1MB in Node.js
      }
    }
  }
}

Authentication Options

The server supports multiple authentication methods with the following priority order:

In-cluster (if running in a pod)
KUBECONFIG_YAML – Full config as YAML string
KUBECONFIG_JSON – Full config as JSON string
K8S_SERVER + K8S_TOKEN – Minimal env-based config
KUBECONFIG_PATH – Custom kubeconfig file path
Default file – ~/.kube/config

Environment Variables

Full YAML Configuration

Set your entire kubeconfig as a YAML string:

export KUBECONFIG_YAML=$(cat << 'EOF'
apiVersion: v1
kind: Config
clusters:
- cluster:
    server: https://your-cluster.example.com
    certificate-authority-data: LS0tLS1CRUdJTi...
  name: my-cluster
users:
- name: my-user
  user:
    token: eyJhbGciOiJSUzI1NiIsImtpZCI6...
contexts:
- context:
    cluster: my-cluster
    user: my-user
    namespace: default
  name: my-context
current-context: my-context
EOF
)

Full JSON Configuration

Set your entire kubeconfig as a JSON string:

export KUBECONFIG_JSON='{"apiVersion":"v1","kind":"Config","clusters":[{"cluster":{"server":"https://your-cluster.example.com"},"name":"my-cluster"}],"users":[{"name":"my-user","user":{"token":"your-token"}}],"contexts":[{"context":{"cluster":"my-cluster","user":"my-user"},"name":"my-context"}],"current-context":"my-context"}'

Minimal Configuration

For simple server + token authentication:

export K8S_SERVER='https://your-cluster.example.com'
export K8S_TOKEN='eyJhbGciOiJSUzI1NiIsImtpZCI6...'
export K8S_SKIP_TLS_VERIFY='false'  # optional, defaults to false

Custom Kubeconfig Path

Specify a custom path to your kubeconfig file:

export KUBECONFIG_PATH='/path/to/your/custom/kubeconfig'

Context and Namespace Overrides

Override the context and default namespace:

export K8S_CONTEXT='my-specific-context'    # Override kubeconfig context
export K8S_NAMESPACE='my-namespace'         # Override default namespace

These overrides work with any of the authentication methods above.

Example: Complete Environment Setup

# Option 1: Using minimal config with overrides
export K8S_SERVER='https://prod-cluster.example.com'
export K8S_TOKEN='eyJhbGciOiJSUzI1NiIsImtpZCI6...'
export K8S_CONTEXT='production'
export K8S_NAMESPACE='my-app'
export K8S_SKIP_TLS_VERIFY='false'

# Option 2: Using custom kubeconfig path
export KUBECONFIG_PATH='/etc/kubernetes/prod-config'
export K8S_CONTEXT='production'
export K8S_NAMESPACE='my-app'

Claude Desktop Configuration with Environment Variables

For Claude Desktop with environment variables:

{
  "mcpServers": {
    "kubernetes-prod": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "K8S_SERVER": "https://prod-cluster.example.com",
        "K8S_TOKEN": "your-token-here",
        "K8S_CONTEXT": "production",
        "K8S_NAMESPACE": "my-app"
      }
    }
  }
}

Tool Filtering Modes

The server offers several modes to control which tools are available, configured via environment variables. The modes are prioritized as follows:

ALLOWED_TOOLS
ALLOW_ONLY_READONLY_TOOLS
ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS

Allowed Tools List

You can specify a comma-separated list of tool names to enable only those specific tools. This provides fine-grained control over the server's capabilities.

ALLOWED_TOOLS="kubectl_get,kubectl_describe" npx mcp-server-kubernetes

In your Claude Desktop configuration:

{
  "mcpServers": {
    "kubernetes-custom": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOWED_TOOLS": "kubectl_get,kubectl_describe,kubectl_logs"
      }
    }
  }
}

Read-Only Mode

For the strictest level of safety, you can enable read-only mode. This mode only permits tools that cannot alter the cluster state.

ALLOW_ONLY_READONLY_TOOLS=true npx mcp-server-kubernetes

The following tools are available in read-only mode:

kubectl_get
kubectl_describe
kubectl_logs
kubectl_context
explain_resource
list_api_resources
ping

In your Claude Desktop configuration:

{
  "mcpServers": {
    "kubernetes-readonly-strict": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_READONLY_TOOLS": "true"
      }
    }
  }
}

Non-Destructive Mode

If neither of the above modes are active, you can run the server in a non-destructive mode that disables all destructive operations (delete pods, delete deployments, delete namespaces, etc.) by setting the ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS environment variable to true:

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

This feature is particularly useful for:

Production environments: Prevent accidental deletion or modification of critical resources
Shared clusters: Allow multiple users to safely explore the cluster without risk of disruption
Educational settings: Provide a safe environment for learning Kubernetes operations
Demonstration purposes: Show cluster state and resources without modification risk

When enabled, the following destructive operations are disabled:

delete_pod: Deleting pods
delete_deployment: Deleting deployments
delete_namespace: Deleting namespaces
uninstall_helm_chart: Uninstalling Helm charts
delete_cronjob: Deleting cronjobs
cleanup: Cleaning up resources

All read-only operations like listing resources, describing pods, getting logs, etc. remain fully functional.

For Non destructive mode in Claude Desktop, you can specify the env var like this:

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

SSE Transport

To enable SSE transport for mcp-server-kubernetes, use the ENABLE_UNSAFE_SSE_TRANSPORT environment variable.

ENABLE_UNSAFE_SSE_TRANSPORT=1 npx flux159/mcp-server-kubernetes

This will start an http server with the /sse endpoint for server-sent events. Use the PORT env var to configure the server port. Use HOST env var to configure listening on interfaces other than localhost.

ENABLE_UNSAFE_SSE_TRANSPORT=1 PORT=3001 HOST=0.0.0.0 npx flux159/mcp-server-kubernetes

This will allow clients to connect via HTTP to the /sse endpoint and receive server-sent events. You can test this by using curl (using port 3001 from above):

curl https://localhost:3001/sse

You will receive a response like this:

event: endpoint
data: /messages?sessionId=b74b64fb-7390-40ab-8d16-8ed98322a6e6

Take note of the session id and make a request to the endpoint provided:

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 1234, "method": "tools/call", "params": {"name": "list_pods", "namespace": "default"}}'  "https://localhost:3001/messages?sessionId=b74b64fb-7390-40ab-8d16-8ed98322a6e6"

If there's no error, you will receive an event: message response in the localhost:3001/sse session.

Note that normally a client would handle this for you. This is just a demonstration of how to use the SSE transport.

Documentation on Running SSE Mode with Docker

Complete Example Assuming your image name is flux159/mcp-server-kubernetes and you need to map ports and set environment parameters, you can run:

docker  run --rm -it -p 3001:3001 -e ENABLE_UNSAFE_SSE_TRANSPORT=1  -e PORT=3001   -v ~/.kube/config:/home/appuser/.kube/config   flux159/mcp-server-kubernetes:latest

⚠️ Key safety considerations When deploying SSE mode using Docker, due to the insecure SSE transport protocol and sensitive configuration file mounting, you should consider using a proxy to handle authentication & authorization to the MCP server.

mcp config

{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "url": "https://localhost:3001/sse",
      "args": []
    }
  }
}

Why is SSE Transport Unsafe?

SSE transport exposes an http endpoint that can be accessed by anyone with the URL. This can be a security risk if the server is not properly secured. It is recommended to use a secure proxy server to proxy to the SSE endpoint. In addition, anyone with access to the URL will be able to utilize the authentication of your kubeconfig to make requests to your Kubernetes cluster. You should add logging to your proxy in order to monitor user requests to the SSE endpoint.

Advance Docker Usage

Connect to AWS EKS Cluster

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-v",
        "~/.aws:/home/appuser/.aws:ro",
        "-e",
        "AWS_PROFILE=default",
        "-e",
        "AWS_REGION=us-west-2",
        "flux159/mcp-server-kubernetes:latest"
      ]
    }
  }
}

Connect to Google GKE Clusters

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-v",
        "~/.config/gcloud:/home/appuser/.config/gcloud:ro",
        "-e",
        "CLOUDSDK_CORE_PROJECT=my-gcp-project",
        "-e",
        "CLOUDSDK_COMPUTE_REGION=us-central1",
        "flux159/mcp-server-kubernetes:latest"
      ]
    }
  }
}

Connect to Azure AKS Clusters

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-e",
        "AZURE_SUBSCRIPTION=my-subscription-id",
        "flux159/mcp-server-kubernetes:latest"
      ]
    }
  }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!