# Kubernetes MCP server guide ## Overview[​](#overview "Direct link to Overview") An MCP server that interacts with Kubernetes clusters, enabling you to manage and automate tasks within your Kubernetes environment. This server is based on the [MKP (Model Kontext Protocol)](https://github.com/StacklokLabs/mkp) project, which is a native Go implementation of an MCP server for Kubernetes that directly interacts with the Kubernetes API. ## Metadata[​](#metadata "Direct link to Metadata") Expand to view the MCP server's metadata Server metadata ``` Name: io.github.stacklok/k8s Type: container Description: Allows LLM-powered applications to interact with Kubernetes clusters. Tier: Community Status: Active Transport: streamable-http Image: ghcr.io/stackloklabs/mkp/server:0.4.4 Target Port: 8080 Has Provenance: Yes Permissions: Network: Insecure Allow All: true Allow Port: 443 Repository URL: https://github.com/StacklokLabs/mkp Popularity: 59 stars Last Updated: 2026-09-11T02:27:19Z Tools: - list_resources - get_resource - apply_resource Environment Variables: - KUBECONFIG: Path to the kubeconfig file for Kubernetes API authentication (mounted into the container with --volume) Tags: kubernetes, k8s, api, resources, cluster, namespaced, apply, get, list Example Command: thv run k8s ``` ## Usage[​](#usage "Direct link to Usage") * UI * CLI * Kubernetes Select the `k8s` MCP server in the ToolHive registry. The server requires Kubernetes cluster access, so you'll need to configure authentication. In the **Volumes** section, mount your kubeconfig file to provide cluster access. The most common setup is: * **Host path**: `/home/$USER/.kube` (your local kubeconfig directory) * **Container path**: `/home/nonroot/.kube` * **Read only access** (recommended for security) Alternatively, if you have a specific kubeconfig file, mount it directly: * **Host path**: `/path/to/your/kubeconfig` * **Container path**: `/home/nonroot/.kube/config` * **Read only access** Write Operations By default, the server runs in read-only mode. To enable write operations (like applying resources), add the `--read-write=true` argument in the **Command arguments** section. Use with caution in production environments. Security tip Enable outbound network filtering on the **Network Isolation** tab to restrict the server's network access to your Kubernetes cluster endpoints only. Add your cluster's API server host and port (usually 443 or 6443) to the allowed list. Run with the default configuration, mounting your local `.kube` directory as read-only: ``` thv run --volume $HOME/.kube:/home/nonroot/.kube:ro k8s ``` Mount a specific kubeconfig file: ``` thv run --volume /path/to/kubeconfig:/home/nonroot/.kube/config:ro k8s ``` Enable write operations (create/update/delete resources) with the `--read-write` flag: ``` thv run --volume $HOME/.kube:/home/nonroot/.kube:ro \ k8s -- --read-write=true ``` Disable resource discovery to reduce context size in large clusters: ``` thv run --volume $HOME/.kube:/home/nonroot/.kube:ro \ --arg --serve-resources=false \ k8s ``` ToolHive [isolates the server's network access](/toolhive/guides-cli/network-isolation.md) by default, but since the registry can't predict your cluster's API server endpoint, the default profile allows all outbound HTTPS traffic. Create a custom permission profile to restrict network access to your cluster only: k8s-cluster-profile.json ``` { "network": { "outbound": { "insecure_allow_all": false, "allow_host": ["your-cluster-endpoint.com", "kubernetes.default.svc"], "allow_port": [443, 6443] } } } ``` Then run with the custom profile: ``` thv run --volume $HOME/.kube:/home/nonroot/.kube:ro \ --permission-profile k8s-cluster-profile.json \ k8s ``` This example follows the recommended practice of running the MKP MCP server inside the cluster it's managing. A service account is used for authentication. Create a Kubernetes manifest to deploy the MKP server. This example creates a service account with `cluster-admin` permissions for simplicity. In production, create a custom ClusterRole with only the minimum permissions required. mkp.yaml ``` apiVersion: toolhive.stacklok.dev/v1beta1 kind: MCPServer metadata: name: mkp namespace: toolhive-system spec: image: ghcr.io/stackloklabs/mkp/server:0.4.4 transport: streamable-http mcpPort: 8080 proxyPort: 8080 serviceAccount: mkp-sa --- apiVersion: v1 kind: ServiceAccount metadata: name: mkp-sa namespace: toolhive-system --- # NOTE: This ClusterRoleBinding uses cluster-admin for example purposes only. # In production, you should create a custom ClusterRole with the minimum # permissions required by your MCP server instead of using cluster-admin. apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: mkp-sa-cluster-admin subjects: - kind: ServiceAccount name: mkp-sa namespace: toolhive-system roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io ``` Apply the manifest to your Kubernetes cluster: ``` kubectl apply -f mkp.yaml ``` To customize the server's behavior, add CLI arguments to the `spec` section of your manifest. For example, to enable write operations: mkp.yaml ``` spec: # ... args: - '--read-write=true' ``` Configure tools To filter or rename the tools exposed by your MCP server on Kubernetes, use the MCPToolConfig CRD and reference it from your MCPServer with the `toolConfigRef` field. See [Configure tools for MCP servers on Kubernetes](/toolhive/guides-k8s/customize-tools.md). ## Sample prompts[​](#sample-prompts "Direct link to Sample prompts") Here are some sample prompts you can use to interact with the Kubernetes MCP server: * "List all pods in the default namespace" * "Show me the status of all deployments across all namespaces" * "Get the logs from the pod named `nginx-pod` in the default namespace" * "Create a new deployment with 3 replicas of nginx in the production namespace" * "Show me all services in the kube-system namespace" * "List all nodes in the cluster and show their resource usage" * "Get the YAML definition of the deployment named `web-app` in the staging namespace" * "Show me all persistent volume claims that are not bound" * "Apply this ConfigMap to the development namespace" ## Recommended practices[​](#recommended-practices "Direct link to Recommended practices") * **Use read-only mode by default**: Only enable write operations (`--read-write=true`) when necessary and in controlled environments. * **Implement proper RBAC**: When using service accounts, follow the principle of least privilege and grant only the minimum permissions required. * **Customize network isolation**: Restrict network access to your Kubernetes API endpoints only, especially in production environments, since the default profile allows all outbound HTTPS traffic. * **Monitor resource usage**: The server includes built-in rate limiting, but monitor your cluster's API server load when using with AI agents. * **Disable resource discovery in large clusters**: Use `--serve-resources=false` to reduce context size and improve performance in clusters with many resources. * **Secure kubeconfig files**: When mounting kubeconfig files, always use read-only mounts and ensure proper file permissions. * **Use namespace scoping**: When possible, limit the server's access to specific namespaces rather than cluster-wide permissions. * **Enable audit logging**: Configure Kubernetes audit logging to track API calls made by the MCP server for security monitoring.