k8s-mcp-server

K8s MCP Server

      

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.

Demo: Deploy and Troubleshoot WordPress

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.

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..

Demo

How It Works

flowchart LR
    A[User] --> |Asks K8s question| B[Claude]
    B --> |Sends command via MCP| C[K8s MCP Server]
    C --> |Executes kubectl, helm, etc.| D[Kubernetes Cluster]
    D --> |Returns results| C
    C --> |Returns formatted results| B
    B --> |Analyzes & explains| A

Claude can help users by:

• Explaining complex Kubernetes concepts
• Running commands against your cluster
• Troubleshooting issues
• Suggesting optimizations
• Crafting Kubernetes manifests

Quick Start with Claude Desktop

Get Claude helping with your Kubernetes clusters in under 2 minutes:

1. Create or update your Claude Desktop configuration file:

• macOS: Edit $HOME/Library/Application Support/Claude/claude_desktop_config.json
• Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
• Linux: Edit $HOME/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "kubernetes": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
           "ghcr.io/alexei-led/k8s-mcp-server:latest"
         ]
       }
     }
   }

1. Restart Claude Desktop

• After restart, you'll see the Tools icon (🔨) in the bottom right of your input field
• This indicates Claude can now access K8s tools via the MCP server

1. Start using K8s tools directly in Claude Desktop:

• "What Kubernetes contexts do I have available?"
• "Show me all pods in the default namespace"
• "Create a deployment with 3 replicas of nginx:1.21"
• "Explain what's wrong with my StatefulSet 'database' in namespace 'prod'"
• "Deploy the bitnami/wordpress chart with Helm and set service type to LoadBalancer"

Note: Claude Desktop will automatically route K8s commands through the MCP server, allowing natural conversation about your clusters without leaving the Claude interface.

Cloud Providers: For AWS EKS, GKE, or Azure AKS, you'll need additional configuration. See the Cloud Provider Support guide.

Features

• Multiple Kubernetes Tools: kubectl, helm, istioctl, and argocd in one container
• Cloud Providers: Native support for AWS EKS, Google GKE, and Azure AKS
• Security: Runs as non-root user with strict command validation
• Command Piping: Support for common Unix tools like jq, grep, and sed
• Easy Configuration: Simple environment variables for customization

Transport Protocols

The server supports three transport protocols, configured via K8S_MCP_TRANSPORT:

| Transport | Description | Default | |-----------|-------------|---------| | stdio | Standard I/O (Claude Desktop default) | Yes | | streamable-http | HTTP transport (recommended for remote/web clients, MCP spec 2025-11-25) | No | | sse | Server-Sent Events (deprecated, use streamable-http instead) | No |

Example using Streamable HTTP transport:

docker run --rm -p 8000:8000 \
  -v ~/.kube:/home/appuser/.kube:ro \
  -e K8S_MCP_TRANSPORT=streamable-http \
  ghcr.io/alexei-led/k8s-mcp-server:latest

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.

Documentation

• Getting Started Guide - Detailed setup instructions
• Cloud Provider Support - EKS, GKE, and AKS configuration
• Supported Tools - Complete list of all included CLI tools
• Environment Variables - Configuration options
• Security Features - Security modes and custom rules
• Claude Integration - Detailed Claude Desktop setup
• Architecture - System architecture and components
• Detailed Specification - Complete technical specification

Usage Examples

Once connected, you can ask Claude to help with Kubernetes tasks using natural language:

flowchart TB
    subgraph "Basic Commands"
        A1["Show me all pods in the default namespace"]
        A2["Get all services across all namespaces"]
        A3["Display the logs for the nginx pod"]
    end
    
    subgraph "Troubleshooting"
        B1["Why is my deployment not starting?"]
        B2["Describe the failing pod and explain the error"]
        B3["Check if my service is properly connected to the pods"]
    end
    
    subgraph "Deployments & Configuration"
        C1["Deploy the Nginx Helm chart"]
        C2["Create a deployment with 3 replicas of nginx:latest"]
        C3["Set up an ingress for my service"]
    end
    
    subgraph "Advanced Operations"
        D1["Check the status of my Istio service mesh"]
        D2["Set up a canary deployment with 20% traffic to v2"]
        D3["Create an ArgoCD application for my repo"]
    end

Claude 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.

Advanced Claude Desktop Configuration

Configure Claude Desktop to optimize your Kubernetes workflow:

Target Specific Clusters and Namespaces

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_CONTEXT=production-cluster",
        "-e", "K8S_NAMESPACE=my-application",
        "-e", "K8S_MCP_TIMEOUT=600",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Connect to AWS EKS Clusters

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
        "-e", "AWS_PROFILE=production",
        "-e", "AWS_REGION=us-west-2",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Connect to Google GKE Clusters

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.config/gcloud:/home/appuser/.config/gcloud:ro",
        "-e", "CLOUDSDK_CORE_PROJECT=my-gcp-project",
        "-e", "CLOUDSDK_COMPUTE_REGION=us-central1",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Connect to Azure AKS Clusters

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.azure:/home/appuser/.azure:ro",
        "-e", "AZURE_SUBSCRIPTION=my-subscription-id",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Permissive Security Mode

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_MCP_SECURITY_MODE=permissive",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

For detailed security configuration options, see Security Documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.