k8s

k8s-mcp-server exposes Kubernetes resources as structured MCP tools, enabling AI agents to safely interact with a Kubernetes cluster through the MCP interface. It supports a wide range of Kubernetes objects such as Pod, Deployment, DaemonSet, StatefulSet, Namespace, Service, ConfigMap, Secret, Node, ServiceAccount, PVC, PV, Roles and Bindings, StorageClass, and CRD operations including Create, Get, List, Update, and Delete where applicable. In addition to predefined resource tools, the server provides a generic Custom Tool that can interact with any CRD or non-explicitly supported resource by forwarding requests to a gRPC backend that resolves the resource dynamically. All interactions are performed using the Kubernetes API with the provided kubeconfig, ensuring operations are governed by the permissions defined in that kubeconfig.

To use the server, start it with your kubeconfig path and, if needed, the custom URL for the dynamic Custom Tool. Once running, an AI agent can issue MCP-style commands to manage resources, retrieve logs, or interact with custom resources via the gRPC backend. The Custom Tool supports Create, Get, List and Delete operations, enabling flexible work with CRDs and newly introduced resources without updating the MCP server.

Prerequisites:

• Go (1.20+ recommended)
• Access to a Kubernetes cluster and a kubeconfig file
• MCP-supported environment or application for integration

Installation steps:

1. Ensure Go is installed and your environment is configured (GOPATH, GOBIN may be needed).
2. Install the MCP server binary:

go install github.com/naveenthangaraj03/k8s-mcp-server@latest

3. Verify the binary is available in your PATH:

k8s-mcp-server --help

4. Prepare your kubeconfig and run the server with the path to kubeconfig:

k8s-mcp-server --kubeconfigPath=/path/to/your/kubeconfig

Optional: enable the custom tool by providing the Custom URL to the gRPC backend if your setup requires dynamic CRD handling:

k8s-mcp-server --kubeconfigPath=/path/to/your/kubeconfig --customURL=grpc://your-backend:port

Note: Replace the placeholder paths and URLs with your actual configuration values.

Tips and considerations:

• The server relies on the RBAC permissions defined in your kubeconfig; ensure the credentials have the necessary access for the resources and operations you intend to perform.
• For CRDs or resources not explicitly listed, use the Custom Tool to forward requests to a dynamic gRPC backend.
• If you encounter authentication or authorization issues, verify cluster RBAC roles, kubeconfig context, and the service account used by the MCP client.
• When deploying in secure environments, consider restricting access to the MCP endpoint and enabling TLS where supported by your integration layer.
• The server supports Create operations with JSON payloads for resources that accept structured data; consult the respective resource README for field-level details.