mcp-server-kubernetes 2.1.0 → 2.2.0

package/README.md

@@ -11,12 +11,13 @@
 [![Last Commit](https://img.shields.io/github/last-commit/Flux159/mcp-server-kubernetes)](https://github.com/Flux159/mcp-server-kubernetes/commits/main)
 [![smithery badge](https://smithery.ai/badge/mcp-server-kubernetes)](https://smithery.ai/protocol/mcp-server-kubernetes)
 
-MCP Server that can connect to a Kubernetes cluster and manage it.
+MCP Server that can connect to a Kubernetes cluster and manage it. Supports loading kubeconfig from multiple sources in priority order.
 
 https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed
 
 <a href="https://glama.ai/mcp/servers/w71ieamqrt"><img width="380" height="200" src="https://glama.ai/mcp/servers/w71ieamqrt/badge" /></a>
 
+
 ## Usage with Claude Desktop
 
 ```json
@@ -30,6 +31,8 @@ https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed
 }
 ```
 
+By default, the server loads kubeconfig from `~/.kube/config`. For additional authentication options (environment variables, custom paths, etc.), see [ADVANCED_README.md](ADVANCED_README.md).
+
 The server will automatically connect to your current kubectl context. Make sure you have:
 
 1. kubectl installed and in your PATH
@@ -175,6 +178,25 @@ For Claude Desktop configuration with non-destructive mode:
 }
 ```
 
+### Commands Available in Non-Destructive Mode
+
+All read-only and resource creation/update operations remain available:
+
+- Resource Information: `kubectl_get`, `kubectl_describe`, `kubectl_list`, `kubectl_logs`, `explain_resource`, `list_api_resources`
+- Resource Creation/Modification: `kubectl_apply`, `kubectl_create`, `kubectl_scale`, `kubectl_patch`, `kubectl_rollout`
+- Helm Operations: `install_helm_chart`, `upgrade_helm_chart`
+- Connectivity: `port_forward`, `stop_port_forward`
+- Context Management: `kubectl_context`
+
+### Commands Disabled in Non-Destructive Mode
+
+The following destructive operations are disabled:
+
+- `kubectl_delete`: Deleting any Kubernetes resources
+- `uninstall_helm_chart`: Uninstalling Helm charts
+- `cleanup`: Cleanup of managed resources
+- `kubectl_generic`: General kubectl command access (may include destructive operations)
+
 For additional advanced features, see the [ADVANCED_README.md](ADVANCED_README.md).
 
 ## Architecture
@@ -190,19 +212,34 @@ The sequence diagram below illustrates how requests flow through the system:
 ```mermaid
 sequenceDiagram
     participant Client
-    participant Transport as StdioTransport
+    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
 
-    Client->>Transport: Send Request via STDIO
+    Note over Transport: StdioTransport or<br>SSE Transport
+
+    Client->>Transport: Send Request
     Transport->>Server: Forward Request
 
     alt Tools Request
-        Server->>Handler: Route to tools handler
-        Handler->>K8sManager: Execute kubectl operation
-        K8sManager->>K8s: Make API call
+        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
@@ -219,6 +256,8 @@ sequenceDiagram
     Transport-->>Client: Return Final Response
 ```
 
+See this [DeepWiki link](https://deepwiki.com/Flux159/mcp-server-kubernetes) for a more indepth architecture overview created by Devin.
+
 ## Publishing new release
 
 Go to the [releases page](https://github.com/Flux159/mcp-server-kubernetes/releases), click on "Draft New Release", click "Choose a tag" and create a new tag by typing out a new version number using "v{major}.{minor}.{patch}" semver format. Then, write a release title "Release v{major}.{minor}.{patch}" and description / changelog if necessary and click "Publish Release".
@@ -227,4 +266,4 @@ This will create a new tag which will trigger a new release build via the cd.yml
 
 ## Not planned
 
-Authentication / adding clusters to kubectx.
+Adding clusters to kubectx.

package/dist/index.js

@@ -29,6 +29,7 @@ const destructiveTools = [
     kubectlDeleteSchema, // This replaces all individual delete operations 
     uninstallHelmChartSchema,
     cleanupSchema, // Cleanup is also destructive as it deletes resources
+    kubectlGenericSchema, // Generic kubectl command can perform destructive operations
 ];
 // Get all available tools
 const allTools = [
@@ -181,7 +182,7 @@ if (process.env.ENABLE_UNSAFE_SSE_TRANSPORT) {
 }
 else {
     const transport = new StdioServerTransport();
-    console.log(`Starting Kubernetes MCP server v${serverConfig.version}, handling commands...`);
+    console.error(`Starting Kubernetes MCP server v${serverConfig.version}, handling commands...`);
     server.connect(transport);
 }
 ["SIGINT", "SIGTERM"].forEach((signal) => {

package/dist/tools/kubectl-generic.js

@@ -97,7 +97,7 @@ export async function kubectlGeneric(k8sManager, input) {
         // Execute the command (join all args except the first "kubectl" which is used in execSync)
         const command = cmdArgs.slice(1).join(' ');
         try {
-            console.log(`Executing: kubectl ${command}`);
+            console.error(`Executing: kubectl ${command}`);
             const result = execSync(`kubectl ${command}`, { encoding: "utf8" });
             return {
                 content: [

package/dist/utils/kubernetes-manager.d.ts

@@ -13,6 +13,38 @@ export declare class KubernetesManager {
      * A very simple test to check if the application is running inside a Kubernetes cluster
      */
     private isRunningInCluster;
+    /**
+     * Check if KUBECONFIG_YAML environment variable is available
+     */
+    private hasEnvKubeconfigYaml;
+    /**
+     * Check if KUBECONFIG_JSON environment variable is available
+     */
+    private hasEnvKubeconfigJson;
+    /**
+     * Check if minimal K8S_SERVER and K8S_TOKEN environment variables are available
+     */
+    private hasEnvMinimalKubeconfig;
+    /**
+     * Load kubeconfig from KUBECONFIG_PATH environment variable (file path)
+     */
+    private loadEnvKubeconfigPath;
+    /**
+     * Load kubeconfig from KUBECONFIG_YAML environment variable (YAML format)
+     */
+    private loadEnvKubeconfigYaml;
+    /**
+     * Load kubeconfig from KUBECONFIG_JSON environment variable (JSON format)
+     */
+    private loadEnvKubeconfigJson;
+    /**
+     * Load kubeconfig from minimal K8S_SERVER and K8S_TOKEN environment variables
+     */
+    private loadEnvMinimalKubeconfig;
+    /**
+     * Check if KUBECONFIG_PATH environment variable is available
+     */
+    private hasEnvKubeconfigPath;
     /**
      * Set the current context to the desired context name.
      *
@@ -30,4 +62,9 @@ export declare class KubernetesManager {
     getCoreApi(): k8s.CoreV1Api;
     getAppsApi(): k8s.AppsV1Api;
     getBatchApi(): k8s.BatchV1Api;
+    /**
+     * Get the default namespace for operations
+     * Uses K8S_NAMESPACE environment variable if set, otherwise defaults to "default"
+     */
+    getDefaultNamespace(): string;
 }

package/dist/utils/kubernetes-manager.js

@@ -11,11 +11,59 @@ export class KubernetesManager {
     constructor() {
         this.kc = new k8s.KubeConfig();
         if (this.isRunningInCluster()) {
+            // Priority 1: In-cluster configuration (existing)
             this.kc.loadFromCluster();
         }
+        else if (this.hasEnvKubeconfigYaml()) {
+            // Priority 2: Full kubeconfig as YAML string
+            try {
+                this.loadEnvKubeconfigYaml();
+            }
+            catch (error) {
+                throw new Error(`Failed to parse KUBECONFIG_YAML: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        else if (this.hasEnvKubeconfigJson()) {
+            // Priority 3: Full kubeconfig as JSON string
+            try {
+                this.loadEnvKubeconfigJson();
+            }
+            catch (error) {
+                throw new Error(`Failed to parse KUBECONFIG_JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        else if (this.hasEnvMinimalKubeconfig()) {
+            // Priority 4: Minimal config with individual environment variables
+            try {
+                this.loadEnvMinimalKubeconfig();
+            }
+            catch (error) {
+                throw new Error(`Failed to create kubeconfig from K8S_SERVER and K8S_TOKEN: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        else if (this.hasEnvKubeconfigPath()) {
+            // Priority 5: Custom kubeconfig file path
+            try {
+                this.loadEnvKubeconfigPath();
+            }
+            catch (error) {
+                throw new Error(`Failed to load kubeconfig from KUBECONFIG_PATH: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
         else {
+            // Priority 6: Default file-based configuration (existing fallback)
             this.kc.loadFromDefault();
         }
+        // Apply context override if specified
+        if (process.env.K8S_CONTEXT) {
+            try {
+                this.setCurrentContext(process.env.K8S_CONTEXT);
+            }
+            catch (error) {
+                console.warn(`Warning: Could not set context to ${process.env.K8S_CONTEXT}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        // Initialize API clients
         this.k8sApi = this.kc.makeApiClient(k8s.CoreV1Api);
         this.k8sAppsApi = this.kc.makeApiClient(k8s.AppsV1Api);
         this.k8sBatchApi = this.kc.makeApiClient(k8s.BatchV1Api);
@@ -32,6 +80,80 @@ export class KubernetesManager {
             return false;
         }
     }
+    /**
+     * Check if KUBECONFIG_YAML environment variable is available
+     */
+    hasEnvKubeconfigYaml() {
+        return !!(process.env.KUBECONFIG_YAML && process.env.KUBECONFIG_YAML.trim());
+    }
+    /**
+     * Check if KUBECONFIG_JSON environment variable is available
+     */
+    hasEnvKubeconfigJson() {
+        return !!(process.env.KUBECONFIG_JSON && process.env.KUBECONFIG_JSON.trim());
+    }
+    /**
+     * Check if minimal K8S_SERVER and K8S_TOKEN environment variables are available
+     */
+    hasEnvMinimalKubeconfig() {
+        return !!(process.env.K8S_SERVER &&
+            process.env.K8S_SERVER.trim() &&
+            process.env.K8S_TOKEN &&
+            process.env.K8S_TOKEN.trim());
+    }
+    /**
+     * Load kubeconfig from KUBECONFIG_PATH environment variable (file path)
+     */
+    loadEnvKubeconfigPath() {
+        this.kc.loadFromFile(process.env.KUBECONFIG_PATH);
+    }
+    /**
+     * Load kubeconfig from KUBECONFIG_YAML environment variable (YAML format)
+     */
+    loadEnvKubeconfigYaml() {
+        this.kc.loadFromString(process.env.KUBECONFIG_YAML);
+    }
+    /**
+     * Load kubeconfig from KUBECONFIG_JSON environment variable (JSON format)
+     */
+    loadEnvKubeconfigJson() {
+        const configObj = JSON.parse(process.env.KUBECONFIG_JSON);
+        this.kc.loadFromOptions(configObj);
+    }
+    /**
+     * Load kubeconfig from minimal K8S_SERVER and K8S_TOKEN environment variables
+     */
+    loadEnvMinimalKubeconfig() {
+        if (!process.env.K8S_SERVER || !process.env.K8S_TOKEN) {
+            throw new Error('K8S_SERVER and K8S_TOKEN environment variables are required');
+        }
+        const cluster = {
+            name: 'env-cluster',
+            server: process.env.K8S_SERVER,
+            skipTLSVerify: process.env.K8S_SKIP_TLS_VERIFY === 'true'
+        };
+        const user = {
+            name: 'env-user',
+            token: process.env.K8S_TOKEN
+        };
+        const context = {
+            name: 'env-context',
+            user: user.name,
+            cluster: cluster.name
+        };
+        this.kc.loadFromOptions({
+            clusters: [cluster],
+            users: [user],
+            contexts: [context],
+            currentContext: context.name
+        });
+    }
+    /**
+     * Check if KUBECONFIG_PATH environment variable is available
+     */
+    hasEnvKubeconfigPath() {
+        return !!(process.env.KUBECONFIG_PATH && process.env.KUBECONFIG_PATH.trim());
+    }
     /**
      * Set the current context to the desired context name.
      *
@@ -110,4 +232,11 @@ export class KubernetesManager {
     getBatchApi() {
         return this.k8sBatchApi;
     }
+    /**
+     * Get the default namespace for operations
+     * Uses K8S_NAMESPACE environment variable if set, otherwise defaults to "default"
+     */
+    getDefaultNamespace() {
+        return process.env.K8S_NAMESPACE || 'default';
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-kubernetes",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for interacting with Kubernetes clusters via kubectl",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
     "@types/express": "5.0.1",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.9.3",
+    "esbuild": "0.21.5",
     "shx": "0.3.4",
     "typescript": "5.6.2",
     "vitest": "2.1.9"