This MCP server provides tools to interact with Kubernetes clusters via a Model Context Protocol interface. It exposes two primary tools: getResource for retrieving a specific Kubernetes resource by kind, name, and optional namespace; and listResources for listing resources with optional namespace and label-based filtering. The server supports both in-cluster and external configurations, using the Kubernetes Go client library under the hood. You can operate it from an MCP client by calling the tools with the appropriate parameters, and the server will return structured data representing the Kubernetes objects.

To get started, run the server in your environment (in-cluster or with a kubeconfig), then use the MCP client to call the tools. For example, you can fetch a Pod named my-pod in the default namespace, list Deployments in a specific namespace, or filter Pods with a label selector like app=nginx. The server handles authentication via kubeconfig when outside the cluster and uses the in-cluster service account when configured to do so. It also provides configurable logging for easier debugging and operational insight.

Prerequisites:

• Go 1.23.2 or later
• Access to a Kubernetes cluster
• If running outside the cluster, a valid kubeconfig file

Installation and setup:

1. Clone the repository git clone https://github.com/HomayoonAlimohammadi/k8s-mcp-server cd k8s-mcp-server

2. Build from source make build

   This will produce the binary in ./bin/k8s-mcp-server

3. Run the server (example)

   Using default configuration

   ./bin/k8s-mcp-server

4. Optional: customize environment variables SERVER_NAME=my-k8s-server
   LOG_LEVEL=debug
   KUBECONFIG=/path/to/kubeconfig
   K8S_IN_CLUSTER=false
   ./bin/k8s-mcp-server

Note: If you prefer a containerized approach, you can build a Docker image with the Go binary and run it via Docker commands.

Environment variables:

• SERVER_NAME: Identifier for the server (default: k8s-mcp-server)
• SERVER_VERSION: Server version (default: 1.0.0)
• KUBECONFIG: Path to kubeconfig when running outside the cluster (default: ~/.kube/config)
• K8S_IN_CLUSTER: Set to true to use in-cluster configuration (default: false)
• LOG_LEVEL: Logging level (debug, info, warn, error) (default: info)
• LOG_FORMAT: Log format (text, json) (default: text) Tips and common issues:
• Ensure access to the Kubernetes cluster from the host or environment where the server runs.
• If running inside a cluster, enable K8S_IN_CLUSTER=true and remove or adjust KUBECONFIG.
• Validate that kubectl can access the cluster using the same kubeconfig or in-cluster credentials.
• If you encounter network or authentication errors, verify permissions for the service account or kubeconfig context.
• The server supports filtering via labelSelector when listing resources; ensure you pass valid label selectors (e.g., app=nginx).