MCP Server Kubernetes

The node_management tool allows you to manage Kubernetes nodes through several operations: listing nodes, cordoning (marking as unschedulable), draining (evicting pods for maintenance), and uncordoning (re-enabling scheduling).

Available Operations

• list: Lists all nodes in the cluster with their current status.
• cordon: Marks a specific node as unschedulable to prevent new pods from being scheduled.
• drain: Safely evicts pods from a node. This is a destructive operation that requires specific safety parameters.
• uncordon: Re-enables scheduling on a previously cordoned node.

Safety Features

• Dry Run: Use dryRun: true to preview an operation without executing it.
• Confirmation: Drain operations require confirmDrain: true to proceed.
• DaemonSet Protection: Use ignoreDaemonsets: true to prevent drain failures caused by DaemonSet pods.
• Timeouts: Use the timeout parameter to prevent hanging operations.

{
  "operation": "list"
}

The server follows a layered architecture to process requests from a client (like Claude Desktop or VS Code) to the Kubernetes API.

1. Transport Layer: Receives requests via StdioTransport or SSE Transport.
2. Tool Filter: If a tool request is made, the server checks if it is in non-destructive mode. If so, it filters out destructive tools.
3. Request Handler: Routes the request to the appropriate handler (Tools or Resources).
4. KubernetesManager: Executes the specific operation (kubectl, Helm, or Port Forwarding) by making API calls to the Kubernetes cluster.
5. Response: The result is processed by the handler and sent back through the transport layer to the client.

sequenceDiagram
    participant Client
    participant Transport as Transport Layer
    participant Server as MCP Server
    participant Filter as Tool Filter
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Note over Transport: StdioTransport or<br>SSE Transport

    Client->>Transport: Send Request
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Filter: Filter available tools
        Note over Filter: Remove destructive tools<br>if in non-destructive mode
        Filter->>Handler: Route to tools handler

        alt kubectl operations
            Handler->>K8sManager: Execute kubectl operation
            K8sManager->>K8s: Make API call
        else Helm operations
            Handler->>K8sManager: Execute Helm operation
            K8sManager->>K8s: Make API call
        else Port Forward operations
            Handler->>K8sManager: Set up port forwarding
            K8sManager->>K8s: Make API call
        end

        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

The server supports multiple authentication methods, applied in the following priority order:

1. KUBECONFIG_YAML: Full configuration as a YAML string.
2. KUBECONFIG_JSON: Full configuration as a JSON string.
3. K8S_SERVER + K8S_TOKEN: Minimal environment-based configuration.
4. In-cluster: Automatic detection if running inside a Kubernetes pod.
5. KUBECONFIG_PATH: Path to a custom kubeconfig file.
6. KUBECONFIG: Standard kubeconfig environment variable.
7. Default file: ~/.kube/config.

Note on TLS: If you provide K8S_CA_DATA (a base64-encoded CA certificate), K8S_SKIP_TLS_VERIFY is automatically forced to false to ensure secure communication.

# Example: Minimal configuration with overrides
export K8S_SERVER='https://prod-cluster.example.com'
export K8S_TOKEN='eyJhbGciOiJSUzI1NiIsImtpZCI6...'
export K8S_CA_DATA='LS0tLS1CRUdJTi...'  # base64-encoded CA certificate
export K8S_CONTEXT='production'
export K8S_NAMESPACE='my-app'
export K8S_SKIP_TLS_VERIFY='false'

You can provide kubeconfigs via URLs or by mounting them from existing Kubernetes volumes (Secrets or ConfigMaps).

URL-based provider: Set kubeconfig.provider=url and provide a list of configurations with name and url keys.

Volume-based provider: Set kubeconfig.provider=volume. This is useful for using pre-existing Secrets/ConfigMaps or external secret managers. You must specify the path within the container, the volumeSpec (e.g., secret.secretName), and the volumeMountSpec (e.g., mountPath).

# URL-based example
helm install mcp-server-k8s ./helm-chart \
  --set kubeconfig.provider=url \
  --set kubeconfig.url.configs[0].name=prod-config \
  --set kubeconfig.url.configs[0].url="https://storage.company.com/prod.yaml"

# Volume-based example (CLI)
helm install mcp-server-k8s ./helm-chart \
  --set kubeconfig.provider=volume \
  --set kubeconfig.volume.path=/home/node/.kube/config \
  --set kubeconfig.volume.volumeSpec.name=kubeconfig \
  --set kubeconfig.volume.volumeSpec.secret.secretName=my-kubeconfig-secret \
  --set kubeconfig.volume.volumeMountSpec.name=kubeconfig \
  --set kubeconfig.volume.volumeMountSpec.mountPath=/home/node/.kube \
  --set kubeconfig.volume.volumeMountSpec.readOnly=true