Manage Your Kubernetes Cluster with k8s mcp-server
# Add to your Claude Code skills
git clone https://github.com/reza-gholizade/k8s-mcp-serverA Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.
A hosted deployment is available on Fronteir AI.
kubectl describe.No comments yet. Be the first to share your thoughts!
stdiossestreamable-http--readonlykubectl configured with appropriate cluster accessClone the repository:
git clone https://github.com/reza-gholizade/k8s-mcp-server.git
cd k8s-mcp-server
Install dependencies:
go mod download
Build the server:
go build -o k8s-mcp-server main.go
The server can run in three modes, configurable via command-line flags or environment variables.
This mode uses standard input/output for communication.
./k8s-mcp-server --mode stdio
Or using environment variables:
SERVER_MODE=stdio ./k8s-mcp-server
This mode starts an HTTP server with Server-Sent Events support.
Default (port 8080):
./k8s-mcp-server --mode sse
Specify a port:
./k8s-mcp-server --mode sse --port 9090
Or using environment variables:
SERVER_MODE=sse SERVER_PORT=9090 ./k8s-mcp-server
This mode starts an HTTP server with streamable-http transport support, following the MCP specification.
Default (port 8080):
./k8s-mcp-server --mode streamable-http
Specify a port:
./k8s-mcp-server --mode streamable-http --port 9090
Or using environment variables:
SERVER_MODE=streamable-http SERVER_PORT=9090 ./k8s-mcp-server
The server will be available at http://localhost:8080/mcp (or your specified port).
If no mode is specified, it defaults to SSE on port 8080.
The server supports multiple authentication methods, which are tried in the following order of priority:
You can provide the entire kubeconfig file content via the KUBECONFIG_DATA environment variable:
export KUBECONFIG_DATA="$(cat ~/.kube/config)"
./k8s-mcp-server
This is useful when you want to avoid mounting files or when running in environments where file access is restricted.
You can authenticate using a Kubernetes API server URL and bearer token:
export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
export KUBERNETES_TOKEN="your-bearer-token-here"
./k8s-mcp-server
Optional environment variables for TLS configuration:
KUBERNETES_CA_CERT: CA certificate content (base64-encoded or PEM format)KUBERNETES_CA_CERT_PATH: Path to CA certificate fileKUBERNETES_INSECURE: Set to "true" to skip TLS verification (not recommended for production)Example with CA certificate:
export KUBERNETES_SERVER="https://kubernetes.example.com:6443"
export KUBERNETES_TOKEN="your-bearer-token-here"
export KUBERNETES_CA_CERT_PATH="/path/to/ca.crt"
./k8s-mcp-server
When running inside a Kubernetes cluster, the server automatically detects and uses the service account token from /var/run/secrets/kubernetes.io/serviceaccount/token. This is the recommended method for running the server as a pod within a cluster.
Example Deployment:
apiVersion: v1
kind: ServiceAccount
metadata:
name: k8s-mcp-server-sa
namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: k8s-mcp-server-role
rules:
- apiGroups: [""]
resources: ["*"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["apps"]
resources: ["*"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
# Add more rules as needed for your use case
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: k8s-mcp-server-rb
subjects:
- kind: ServiceAccount
name: k8s-mcp-server-sa
namespace: default
roleRef:
kind: ClusterRole
name: k8s-mcp-server-role
apiGroup: rbac.authorization.k8s.io
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: k8s-mcp-server
namespace: default
spec:
replicas: 1
selector:
matchLabels:
app: k8s-mcp-server
template:
metadata:
labels:
app: k8s-mcp-server
spec:
serviceAccountName: k8s-mcp-server-sa
containers:
- name: k8s-mcp-server
image: ginnux/k8s-mcp-server:latest
ports:
- containerPort: 8080
env:
- name: SERVER_MODE
value: "sse"
- name: SERVER_PORT
value: "8080"
If none of the above methods are available, the server falls back to using a kubeconfig file:
--kubeconfig flag (if implemented) or KUBECONFIG environment variable~/.kube/config if neither is specified# Using default ~/.kube/config
./k8s-mcp-server
# Using custom kubeconfig path
export KUBECONFIG=/path/to/your/kubeconfig
./k8s-mcp-server
Note: The server automatically detects which authentication method to use based on the available environment variables and file system. You don't need to explicitly configure the authentication method - it will use the first available method in the priority order listed above.
The server supports a read-only mode that disables all write operations, providing a safer way to explore and monitor your Kubernetes cluster without the risk of making changes.
Enable read-only mode with the --read-only flag:
./k8s-mcp-server --read-only
You can combine read-only mode with any server mode:
# Read-only with stdio mode
./k8s-mcp-server --mode stdio --read-only
# Read-only with SSE mode
./k8s-mcp-server --mode sse --read-only
# Read-only with streamable-http mode
./k8s-mcp-server --mode streamable-http --read-only
When read-only mode is enabled, the following tools are disabled:
createResource (Kubernetes resource creation/updates)helmInstall (Helm chart installations)helmUpgrade (Helm chart upgrades)helmUninstall (Helm chart uninstallations)helmRollback (Helm release rollbacks)helmRepoAdd (Helm repository additions)All other read-only operations remain available, including listing resources, getting logs, viewing metrics, and inspecting Helm releases.
You can selectively disable entire categories of tools using these flags:
Disable Kubernetes Tools:
./k8s-mcp-server --no-k8s
Disable Helm Tools:
./k8s-mcp-server --no-helm
Combine with other flags:
# Read-only mode with only Kubernetes tools (no Helm)
./k8s-mcp-server --read-only --no-helm
# Read-only mode with only Helm tools (no Kubernetes)
./k8s-mcp-server --read-only --no-k8s
# SSE mode with only Kubernetes tools
./k8s-mcp-server --mode sse --no-helm
Note: You cannot use both --no-k8s and --no-helm together, as this would result in no available tools. The server will exit with an error if both flags are provided.
When --no-k8s is enabled, all Kubernetes tools are disabled:
getAPIResources, listResources, getResource, describeResourcegetPodsLogs, getNodeMetrics, getPodMetrics, getEventscreateResource (if not in read-only mode)When --no-helm is enabled, all Helm tools are disabled:
helmList, helmGet, helmHistory, helmRepoListhelmInstall, helmUpgrade, helmUninstall, helmRollback, helmRepoAdd (if not in read-only mode)You can also run the server using the pre-built Docker image from Docker Hub.
Pull the image:
docker pull ginnux/k8s-mcp-server:latest
You can replace latest with a specific version tag (e.g., 1.0.0).
Run the container:
Note: The server supports multiple authentication methods. You can either mount a kubeconfig file (as shown below) or use environment variables for authentication (see Kubernetes Authentication section above).
docker run -p 8080:8080 -v ~/.kube/config:/home/appuser/.kube/config:ro ginnux/k8s-mcp-server: