mcp-server-kubernetes 0.2.5 → 0.3.1

package/README.md

@@ -6,6 +6,8 @@ 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>
 
+[![smithery badge](https://smithery.ai/badge/mcp-server-kubernetes)](https://smithery.ai/server/mcp-server-kubernetes)
+
 ## Usage with Claude Desktop
 
 ```json
@@ -30,6 +32,28 @@ You can verify your connection by asking Claude to list your pods or create a te
 
 If you have errors open up a standard terminal and run `kubectl get pods` to see if you can connect to your cluster without credentials issues.
 
+## Usage with mcp-chat
+
+[mcp-chat](https://github.com/Flux159/mcp-chat) is a CLI chat client for MCP servers. You can use it to interact with the Kubernetes server.
+
+```shell
+npx mcp-chat --server "npx mcp-server-kubernetes"
+```
+
+Alternatively, pass it your existing Claude Desktop configuration file from above (Linux should pass the correct path to config):
+
+Mac:
+
+```shell
+npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"
+```
+
+Windows:
+
+```shell
+npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
+```
+
 ## Features
 
 - [x] Connect to a Kubernetes cluster
@@ -49,6 +73,8 @@ If you have errors open up a standard terminal and run `kubectl get pods` to see
   - Support for namespaces
   - Support for version specification
   - Support for custom repositories
+- [x] kubectl explain and kubectl api-resources support
+- [x] Get Kubernetes events from the cluster
 - [ ] Port forward to a pod
 - [ ] Choose namespace for next commands (memory)
 
@@ -87,6 +113,12 @@ npx @modelcontextprotocol/inspector node build/index.js
 # Follow further instructions on terminal for Inspector link
 ```
 
+5. Local testing with [mcp-chat](https://github.com/Flux159/mcp-chat)
+
+```bash
+npm run chat
+```
+
 ### Project Structure
 
 ```

package/dist/index.js

@@ -4,12 +4,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { listPods, listPodsSchema } from "./tools/list_pods.js";
 import { listNodes, listNodesSchema } from "./tools/list_nodes.js";
 import { listServices, listServicesSchema } from "./tools/list_services.js";
-import { listDeployments, listDeploymentsSchema } from "./tools/list_deployments.js";
+import { listDeployments, listDeploymentsSchema, } from "./tools/list_deployments.js";
 import { installHelmChart, installHelmChartSchema, upgradeHelmChart, upgradeHelmChartSchema, uninstallHelmChart, uninstallHelmChartSchema, } from "./tools/helm-operations.js";
+import { explainResource, explainResourceSchema, listApiResources, listApiResourcesSchema, } from "./tools/kubectl-operations.js";
 import { createPod, createPodSchema } from "./tools/create_pod.js";
 import { deletePod, deletePodSchema } from "./tools/delete_pod.js";
 import { describePod, describePodSchema } from "./tools/describe_pod.js";
 import { getLogs, getLogsSchema } from "./tools/get_logs.js";
+import { getEvents, getEventsSchema } from "./tools/get_events.js";
 import { getResourceHandlers } from "./resources/handlers.js";
 import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { KubernetesManager } from "./types.js";
@@ -26,20 +28,23 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
         tools: [
-            listPodsSchema,
-            listDeploymentsSchema,
-            listServicesSchema,
-            listNamespacesSchema,
-            createPodSchema,
+            cleanupSchema,
             createDeploymentSchema,
+            createPodSchema,
             deletePodSchema,
             describePodSchema,
-            cleanupSchema,
-            listNodesSchema,
+            explainResourceSchema,
+            getEventsSchema,
             getLogsSchema,
             installHelmChartSchema,
-            upgradeHelmChartSchema,
+            listApiResourcesSchema,
+            listDeploymentsSchema,
+            listNamespacesSchema,
+            listNodesSchema,
+            listPodsSchema,
+            listServicesSchema,
             uninstallHelmChartSchema,
+            upgradeHelmChartSchema,
         ],
     };
 });
@@ -47,27 +52,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const { name, arguments: input = {} } = request.params;
         switch (name) {
-            case "list_pods": {
-                return await listPods(k8sManager, input);
-            }
-            case "list_deployments": {
-                return await listDeployments(k8sManager, input);
-            }
-            case "list_services": {
-                return await listServices(k8sManager, input);
-            }
-            case "list_namespaces": {
-                const { body } = await k8sManager.getCoreApi().listNamespace();
-                const namespaces = body.items.map((ns) => ({
-                    name: ns.metadata?.name || "",
-                    status: ns.status?.phase || "",
-                    createdAt: ns.metadata?.creationTimestamp,
-                }));
+            case "cleanup": {
+                await k8sManager.cleanup();
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ namespaces }, null, 2),
+                            text: JSON.stringify({
+                                success: true,
+                            }, null, 2),
                         },
                     ],
                 };
@@ -81,15 +74,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "describe_pod": {
                 return await describePod(k8sManager, input);
             }
-            case "cleanup": {
-                await k8sManager.cleanup();
+            case "explain_resource": {
+                return await explainResource(input);
+            }
+            case "get_events": {
+                return await getEvents(k8sManager, input);
+            }
+            case "get_logs": {
+                return await getLogs(k8sManager, input);
+            }
+            case "install_helm_chart": {
+                return await installHelmChart(input);
+            }
+            case "list_api_resources": {
+                return await listApiResources(input);
+            }
+            case "list_deployments": {
+                return await listDeployments(k8sManager, input);
+            }
+            case "list_namespaces": {
+                const { body } = await k8sManager.getCoreApi().listNamespace();
+                const namespaces = body.items.map((ns) => ({
+                    name: ns.metadata?.name || "",
+                    status: ns.status?.phase || "",
+                    createdAt: ns.metadata?.creationTimestamp,
+                }));
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                            }, null, 2),
+                            text: JSON.stringify({ namespaces }, null, 2),
                         },
                     ],
                 };
@@ -97,18 +111,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "list_nodes": {
                 return await listNodes(k8sManager);
             }
-            case "get_logs": {
-                return await getLogs(k8sManager, input);
-            }
-            case "install_helm_chart": {
-                return await installHelmChart(input);
+            case "list_pods": {
+                return await listPods(k8sManager, input);
             }
-            case "upgrade_helm_chart": {
-                return await upgradeHelmChart(input);
+            case "list_services": {
+                return await listServices(k8sManager, input);
             }
             case "uninstall_helm_chart": {
                 return await uninstallHelmChart(input);
             }
+            case "upgrade_helm_chart": {
+                return await upgradeHelmChart(input);
+            }
             default:
                 throw new McpError(ErrorCode.InvalidRequest, `Unknown tool: ${name}`);
         }

package/dist/models/kubectl-models.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export declare const KubectlResponseSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export interface ExplainResourceParams {
+    resource: string;
+    apiVersion?: string;
+    recursive?: boolean;
+    output?: "plaintext" | "plaintext-openapiv2";
+}
+export interface ListApiResourcesParams {
+    apiGroup?: string;
+    namespaced?: boolean;
+    verbs?: string[];
+    output?: "wide" | "name" | "no-headers";
+}

package/dist/models/kubectl-models.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const KubectlResponseSchema = z.object({
+    content: z.array(z.object({
+        type: z.literal("text"),
+        text: z.string(),
+    })),
+});

package/dist/models/response-schemas.d.ts

@@ -219,3 +219,25 @@ export declare const GetLogsResponseSchema: z.ZodObject<{
         text: string;
     }[];
 }>;
+export declare const GetEventsResponseSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/models/response-schemas.js

@@ -34,3 +34,6 @@ export const ListNodesResponseSchema = z.object({
 export const GetLogsResponseSchema = z.object({
     content: z.array(ToolResponseContent),
 });
+export const GetEventsResponseSchema = z.object({
+    content: z.array(ToolResponseContent),
+});

package/dist/tools/get_events.d.ts

@@ -0,0 +1,28 @@
+import { KubernetesManager } from "../types.js";
+export declare const getEventsSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            namespace: {
+                type: string;
+                description: string;
+            };
+            fieldSelector: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare function getEvents(k8sManager: KubernetesManager, params: {
+    namespace?: string;
+    fieldSelector?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/get_events.js

@@ -0,0 +1,66 @@
+export const getEventsSchema = {
+    name: "get_events",
+    description: "Get Kubernetes events from the cluster",
+    inputSchema: {
+        type: "object",
+        properties: {
+            namespace: {
+                type: "string",
+                description: "Namespace to get events from. If not specified, gets events from all namespaces",
+            },
+            fieldSelector: {
+                type: "string",
+                description: "Field selector to filter events",
+            },
+        },
+        required: [],
+    },
+};
+export async function getEvents(k8sManager, params) {
+    const { namespace, fieldSelector } = params;
+    const api = k8sManager.getCoreApi();
+    let events;
+    if (namespace) {
+        const { body } = await api.listNamespacedEvent(namespace, undefined, // pretty
+        undefined, // allowWatchBookmarks
+        undefined, // _continue
+        undefined, // fieldSelector
+        fieldSelector // fieldSelector
+        );
+        events = body;
+    }
+    else {
+        const { body } = await api.listEventForAllNamespaces(undefined, // allowWatchBookmarks
+        undefined, // _continue
+        fieldSelector, // fieldSelector
+        undefined, // labelSelector
+        undefined, // limit
+        undefined, // pretty
+        undefined, // resourceVersion
+        undefined, // resourceVersionMatch
+        undefined // timeoutSeconds
+        );
+        events = body;
+    }
+    const formattedEvents = events.items.map((event) => ({
+        type: event.type || "",
+        reason: event.reason || "",
+        message: event.message || "",
+        involvedObject: {
+            kind: event.involvedObject.kind || "",
+            name: event.involvedObject.name || "",
+            namespace: event.involvedObject.namespace || "",
+        },
+        firstTimestamp: event.firstTimestamp || "",
+        lastTimestamp: event.lastTimestamp || "",
+        count: event.count || 0,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ events: formattedEvents }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/kubectl-operations.d.ts

@@ -0,0 +1,72 @@
+import { ExplainResourceParams, ListApiResourcesParams } from "../models/kubectl-models.js";
+export declare const explainResourceSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            resource: {
+                type: string;
+                description: string;
+            };
+            apiVersion: {
+                type: string;
+                description: string;
+            };
+            recursive: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            output: {
+                type: string;
+                description: string;
+                enum: string[];
+                default: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const listApiResourcesSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            apiGroup: {
+                type: string;
+                description: string;
+            };
+            namespaced: {
+                type: string;
+                description: string;
+            };
+            verbs: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            output: {
+                type: string;
+                description: string;
+                enum: string[];
+                default: string;
+            };
+        };
+    };
+};
+export declare function explainResource(params: ExplainResourceParams): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function listApiResources(params: ListApiResourcesParams): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/kubectl-operations.js

@@ -0,0 +1,124 @@
+import { execSync } from "child_process";
+export const explainResourceSchema = {
+    name: "explain_resource",
+    description: "Get documentation for a Kubernetes resource or field",
+    inputSchema: {
+        type: "object",
+        properties: {
+            resource: {
+                type: "string",
+                description: "Resource name or field path (e.g. 'pods' or 'pods.spec.containers')",
+            },
+            apiVersion: {
+                type: "string",
+                description: "API version to use (e.g. 'apps/v1')",
+            },
+            recursive: {
+                type: "boolean",
+                description: "Print the fields of fields recursively",
+                default: false,
+            },
+            output: {
+                type: "string",
+                description: "Output format (plaintext or plaintext-openapiv2)",
+                enum: ["plaintext", "plaintext-openapiv2"],
+                default: "plaintext",
+            },
+        },
+        required: ["resource"],
+    },
+};
+export const listApiResourcesSchema = {
+    name: "list_api_resources",
+    description: "List the API resources available in the cluster",
+    inputSchema: {
+        type: "object",
+        properties: {
+            apiGroup: {
+                type: "string",
+                description: "API group to filter by",
+            },
+            namespaced: {
+                type: "boolean",
+                description: "If true, only show namespaced resources",
+            },
+            verbs: {
+                type: "array",
+                items: {
+                    type: "string",
+                },
+                description: "List of verbs to filter by",
+            },
+            output: {
+                type: "string",
+                description: "Output format (wide, name, or no-headers)",
+                enum: ["wide", "name", "no-headers"],
+                default: "wide",
+            },
+        },
+    },
+};
+const executeKubectlCommand = (command) => {
+    try {
+        return execSync(command, { encoding: "utf8" });
+    }
+    catch (error) {
+        throw new Error(`Kubectl command failed: ${error.message}`);
+    }
+};
+export async function explainResource(params) {
+    try {
+        let command = "kubectl explain";
+        if (params.apiVersion) {
+            command += ` --api-version=${params.apiVersion}`;
+        }
+        if (params.recursive) {
+            command += " --recursive";
+        }
+        if (params.output) {
+            command += ` --output=${params.output}`;
+        }
+        command += ` ${params.resource}`;
+        const result = executeKubectlCommand(command);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to explain resource: ${error.message}`);
+    }
+}
+export async function listApiResources(params) {
+    try {
+        let command = "kubectl api-resources";
+        if (params.apiGroup) {
+            command += ` --api-group=${params.apiGroup}`;
+        }
+        if (params.namespaced !== undefined) {
+            command += ` --namespaced=${params.namespaced}`;
+        }
+        if (params.verbs && params.verbs.length > 0) {
+            command += ` --verbs=${params.verbs.join(",")}`;
+        }
+        if (params.output) {
+            command += ` -o ${params.output}`;
+        }
+        const result = executeKubectlCommand(command);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to list API resources: ${error.message}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-kubernetes",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "MCP server for interacting with Kubernetes clusters via kubectl",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,8 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "prepublishOnly": "npm run build",
-    "dockerbuild": "docker buildx build -t flux159/mcp-server-kubernetes --platform linux/amd64,linux/arm64 --push ."
+    "dockerbuild": "docker buildx build -t flux159/mcp-server-kubernetes --platform linux/amd64,linux/arm64 --push .",
+    "chat": "npx mcp-chat --server \"./dist/index.js\""
   },
   "keywords": [
     "mcp",