reza-gholizade/k8s-mcp-server

A Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.
Hosted deployment
A hosted deployment is available on Fronteir AI.
Features
- **API Resource Discovery**: Get all available API resources in your Kubernetes cluster.
- **Resource Listing**: List resources of any type with optional namespace and label filtering.
- **Resource Details**: Get detailed information about specific Kubernetes resources.
- **Resource Description**: Get comprehensive descriptions of Kubernetes resources, similar to kubectl describe.
- **Pod Logs**: Retrieve logs from specific pods (optionally from a specific container, or all containers if unspecified).
- **Node Metrics**: Get resource usage metrics for specific nodes.
- **Pod Metrics**: Get CPU and Memory metrics for specific pods.
- **Event Listing**: List events within a namespace or for a specific resource.
- **Resource Creation/Updating**: Create new Kubernetes resources or update existing ones from a YAML or JSON manifest.
- **Resource Deletion**: It deletes a resource in the Kubernetes cluster based on the provided namespace and kind.
- **Standardized Interface**: Uses the MCP protocol for consistent tool interaction.
- **Flexible Configuration**: Supports different Kubernetes contexts and resource scopes.
- **Multiple Modes**: Run in stdio mode for CLI tools, sse mode, or streamable-http mode for web applications, and --readonly for no change in the cluster.
- **Security**: Runs as non-root user in Docker containers for enhanced security.
Prerequisites
- Go 1.23 or later
- Access to a Kubernetes cluster
- kubectl configured with appropriate cluster access
Installation
1. **Clone the repository:**
2. **Install dependencies:**
3. **Build the server:**
Usage
Starting the Server
The server can run in three modes, configurable via command-line flags or environment variables.
Stdio Mode (for CLI integrations)
This mode uses standard input/output for communication.
Or using environment variables:
SSE Mode (for web applications)
This mode starts an HTTP server with Server-Sent Events support.
HTTP transports require a bearer token and listen on loopback by default:
Specify a port:
Or using environment variables:
Streamable-HTTP Mode (for web applications)
This mode starts an HTTP server with streamable-http transport support, following the MCP specification.
Default (port 8080):
Specify a port:
Or using environment variables:
The server will be available at http://localhost:8080/mcp (or your specified port).
If no mode is specified, the server defaults to stdio. HTTP modes bind to
127.0.0.1 by default. Set SERVER_HOST=0.0.0.0 (or --host 0.0.0.0) only
when network access is intentional, and send Authorization: Bearer
on every MCP request. Browser clients must also be explicitly allowed with a
comma-separated MCP_ALLOWED_ORIGINS value.
The unauthenticated /healthz endpoint is available for container health checks;
it does not expose MCP functionality.
Kubernetes Authentication
The server supports multiple authentication methods, which are tried in the following order of priority:
1. Kubeconfig Content from Environment Variable
You can provide the entire kubeconfig file content via the KUBECONFIG_DATA environment variable:
This is useful when you want to avoid mounting files or when running in environments where file access is restricted.
2. API Server URL and Token
You can authenticate using a Kubernetes API server URL and bearer token:
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 file
- KUBERNETES_INSECURE: Set to "true" to skip TLS verification (not recommended for production)
Example with CA certificate:
3. In-Cluster Authentication (Service Account)
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:**
4. Kubeconfig File Path (Default)
If none of the above methods are available, the server falls back to using a kubeconfig file: