K8s MCP Server is a Docker-based server implementing Anthropic's Model Context Protocol (MCP) that enables Claude to run Kubernetes CLI tools (kubectl, istioctl, helm, argocd) in a secure, containerized environment. Session 1: Using k8s-mcp-server and Helm CLI to deploy a WordPress application in the claude-demo namespace, then intentionally breaking it by scaling the MariaDB StatefulSet to zero.
Add this skill
npx mdskills install alexei-led/k8s-mcp-serverComprehensive Kubernetes management with excellent auth flexibility and mode support
1# K8s MCP Server23[](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/ci.yml)4[](https://github.com/alexei-led/k8s-mcp-server/actions/workflows/release.yml)5[](https://codecov.io/gh/alexei-led/k8s-mcp-server)6[](https://github.com/alexei-led/k8s-mcp-server/pkgs/container/k8s-mcp-server/versions)7[](https://github.com/alexei-led/k8s-mcp-server/pkgs/container/k8s-mcp-server)8[](https://www.python.org/downloads/)9[](https://opensource.org/licenses/MIT)1011K8s MCP Server is a Docker-based server implementing [Anthropic's Model Context Protocol (MCP)](https://www.anthropic.com/news/introducing-mcp) that enables Claude to run Kubernetes CLI tools (`kubectl`, `istioctl`, `helm`, `argocd`) in a secure, containerized environment.1213## Demo: Deploy and Troubleshoot WordPress1415**Session 1:** Using k8s-mcp-server and Helm CLI to deploy a WordPress application in the claude-demo namespace, then intentionally breaking it by scaling the MariaDB StatefulSet to zero.1617**Session 2:** Troubleshooting session where we use k8s-mcp-server to diagnose the broken WordPress site through kubectl commands, identify the missing database issue, and fix it by scaling up the StatefulSet and configuring ingress access..1819[Demo](https://private-user-images.githubusercontent.com/1898375/428398164-5ddce5bc-ec92-459b-a506-5d4442618a81.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NDMzNDE0OTEsIm5iZiI6MTc0MzM0MTE5MSwicGF0aCI6Ii8xODk4Mzc1LzQyODM5ODE2NC01ZGRjZTViYy1lYzkyLTQ1OWItYTUwNi01ZDQ0NDI2MThhODEubXA0P1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MDMzMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTAzMzBUMTMyNjMxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YmUyNDExMGUzOGRlN2QxNWViMzhhOTE4Y2U1ZmRjMTQxYTI0OGNlNTFjNTRlMjFjNmQ3NTNhNGFmODNkODIzMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.hwKERwuQRXxHEYJ9d_fQ__XL1gj8l76nO6Yy6M4Uov8)2021## How It Works2223```mermaid24flowchart LR25 A[User] --> |Asks K8s question| B[Claude]26 B --> |Sends command via MCP| C[K8s MCP Server]27 C --> |Executes kubectl, helm, etc.| D[Kubernetes Cluster]28 D --> |Returns results| C29 C --> |Returns formatted results| B30 B --> |Analyzes & explains| A31```3233Claude can help users by:34- Explaining complex Kubernetes concepts35- Running commands against your cluster36- Troubleshooting issues37- Suggesting optimizations38- Crafting Kubernetes manifests3940## Quick Start with Claude Desktop4142Get Claude helping with your Kubernetes clusters in under 2 minutes:43441. **Create or update your Claude Desktop configuration file**:45 - **macOS**: Edit `$HOME/Library/Application Support/Claude/claude_desktop_config.json`46 - **Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json`47 - **Linux**: Edit `$HOME/.config/Claude/claude_desktop_config.json`4849 ```json50 {51 "mcpServers": {52 "kubernetes": {53 "command": "docker",54 "args": [55 "run",56 "-i",57 "--rm",58 "-v",59 "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",60 "ghcr.io/alexei-led/k8s-mcp-server:latest"61 ]62 }63 }64 }65 ```66672. **Restart Claude Desktop**68 - After restart, you'll see the Tools icon (🔨) in the bottom right of your input field69 - This indicates Claude can now access K8s tools via the MCP server70713. **Start using K8s tools directly in Claude Desktop**:72 - "What Kubernetes contexts do I have available?"73 - "Show me all pods in the default namespace"74 - "Create a deployment with 3 replicas of nginx:1.21"75 - "Explain what's wrong with my StatefulSet 'database' in namespace 'prod'"76 - "Deploy the bitnami/wordpress chart with Helm and set service type to LoadBalancer"7778> **Note**: Claude Desktop will automatically route K8s commands through the MCP server, allowing natural conversation about your clusters without leaving the Claude interface.7980> **Cloud Providers**: For AWS EKS, GKE, or Azure AKS, you'll need additional configuration. See the [Cloud Provider Support](./docs/cloud-providers.md) guide.8182## Features8384- **Multiple Kubernetes Tools**: `kubectl`, `helm`, `istioctl`, and `argocd` in one container85- **Cloud Providers**: Native support for AWS EKS, Google GKE, and Azure AKS86- **Security**: Runs as non-root user with strict command validation87- **Command Piping**: Support for common Unix tools like `jq`, `grep`, and `sed`88- **Easy Configuration**: Simple environment variables for customization8990## Transport Protocols9192The server supports three transport protocols, configured via `K8S_MCP_TRANSPORT`:9394| Transport | Description | Default |95|-----------|-------------|---------|96| `stdio` | Standard I/O (Claude Desktop default) | Yes |97| `streamable-http` | HTTP transport (recommended for remote/web clients, MCP spec 2025-11-25) | No |98| `sse` | Server-Sent Events (deprecated, use `streamable-http` instead) | No |99100Example using Streamable HTTP transport:101102```bash103docker run --rm -p 8000:8000 \104 -v ~/.kube:/home/appuser/.kube:ro \105 -e K8S_MCP_TRANSPORT=streamable-http \106 ghcr.io/alexei-led/k8s-mcp-server:latest107```108109> **Note**: When running in Docker with HTTP transports, the server automatically binds to `0.0.0.0` for proper port mapping. Outside Docker it binds to `127.0.0.1`.110111## Documentation112113- [Getting Started Guide](./docs/getting-started.md) - Detailed setup instructions114- [Cloud Provider Support](./docs/cloud-providers.md) - EKS, GKE, and AKS configuration115- [Supported Tools](./docs/supported-tools.md) - Complete list of all included CLI tools116- [Environment Variables](./docs/environment-variables.md) - Configuration options117- [Security Features](./docs/security.md) - Security modes and custom rules118- [Claude Integration](./docs/claude-integration.md) - Detailed Claude Desktop setup119- [Architecture](./docs/architecture.md) - System architecture and components120- [Detailed Specification](./docs/spec.md) - Complete technical specification121122## Usage Examples123124Once connected, you can ask Claude to help with Kubernetes tasks using natural language:125126```mermaid127flowchart TB128 subgraph "Basic Commands"129 A1["Show me all pods in the default namespace"]130 A2["Get all services across all namespaces"]131 A3["Display the logs for the nginx pod"]132 end133134 subgraph "Troubleshooting"135 B1["Why is my deployment not starting?"]136 B2["Describe the failing pod and explain the error"]137 B3["Check if my service is properly connected to the pods"]138 end139140 subgraph "Deployments & Configuration"141 C1["Deploy the Nginx Helm chart"]142 C2["Create a deployment with 3 replicas of nginx:latest"]143 C3["Set up an ingress for my service"]144 end145146 subgraph "Advanced Operations"147 D1["Check the status of my Istio service mesh"]148 D2["Set up a canary deployment with 20% traffic to v2"]149 D3["Create an ArgoCD application for my repo"]150 end151```152153Claude can understand your intent and run the appropriate kubectl, helm, istioctl, or argocd commands based on your request. It can then explain the output in simple terms or help you troubleshoot issues.154155## Advanced Claude Desktop Configuration156157Configure Claude Desktop to optimize your Kubernetes workflow:158159### Target Specific Clusters and Namespaces160161```json162{163 "mcpServers": {164 "kubernetes": {165 "command": "docker",166 "args": [167 "run", "-i", "--rm",168 "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",169 "-e", "K8S_CONTEXT=production-cluster",170 "-e", "K8S_NAMESPACE=my-application",171 "-e", "K8S_MCP_TIMEOUT=600",172 "ghcr.io/alexei-led/k8s-mcp-server:latest"173 ]174 }175 }176}177```178179### Connect to AWS EKS Clusters180181```json182{183 "mcpServers": {184 "kubernetes": {185 "command": "docker",186 "args": [187 "run", "-i", "--rm",188 "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",189 "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",190 "-e", "AWS_PROFILE=production",191 "-e", "AWS_REGION=us-west-2",192 "ghcr.io/alexei-led/k8s-mcp-server:latest"193 ]194 }195 }196}197```198199### Connect to Google GKE Clusters200201```json202{203 "mcpServers": {204 "kubernetes": {205 "command": "docker",206 "args": [207 "run", "-i", "--rm",208 "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",209 "-v", "/Users/YOUR_USER_NAME/.config/gcloud:/home/appuser/.config/gcloud:ro",210 "-e", "CLOUDSDK_CORE_PROJECT=my-gcp-project",211 "-e", "CLOUDSDK_COMPUTE_REGION=us-central1",212 "ghcr.io/alexei-led/k8s-mcp-server:latest"213 ]214 }215 }216}217```218219### Connect to Azure AKS Clusters220221```json222{223 "mcpServers": {224 "kubernetes": {225 "command": "docker",226 "args": [227 "run", "-i", "--rm",228 "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",229 "-v", "/Users/YOUR_USER_NAME/.azure:/home/appuser/.azure:ro",230 "-e", "AZURE_SUBSCRIPTION=my-subscription-id",231 "ghcr.io/alexei-led/k8s-mcp-server:latest"232 ]233 }234 }235}236```237238### Permissive Security Mode239240```json241{242 "mcpServers": {243 "kubernetes": {244 "command": "docker",245 "args": [246 "run", "-i", "--rm",247 "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",248 "-e", "K8S_MCP_SECURITY_MODE=permissive",249 "ghcr.io/alexei-led/k8s-mcp-server:latest"250 ]251 }252 }253}254```255256> For detailed security configuration options, see [Security Documentation](./docs/security.md).257258## License259260This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Full transparency — inspect the skill content before installing.