rohitghumare64/kubectl-mcp-server repository overview

kubectl-mcp-server

Control your entire Kubernetes infrastructure through natural language conversations with AI.
Talk to your clusters like you talk to a DevOps expert. Debug crashed pods, optimize costs, deploy applications, audit security, and manage Helm charts, all through natural language.
Part of CNCF Landscape, Next to Terraform

⁠Installation

⁠Quick Start with npx (Recommended - Zero Install)

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

⁠Or install with pip (Python)

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

⁠📑 Table of Contents

• What Can You Do?⁠
• Why kubectl-mcp-server?⁠
• Live Demos⁠
• Installation⁠
  • Quick Start with npx⁠
  • Install with pip⁠
  • Docker⁠
• Getting Started⁠
• Quick Setup with Your AI Assistant⁠
• All Supported AI Assistants⁠
• Complete Feature Set⁠
• Using the CLI⁠
• Advanced Configuration⁠
• Stateless MCP (2026-07-28)⁠
• Enterprise⁠
• Security⁠
• Integrations & Ecosystem⁠
• In-Cluster Deployment⁠
• Multi-Cluster Support⁠
• Architecture⁠
• Agent Skills⁠
• Development & Testing⁠
• Contributing⁠
• Support & Community⁠

⁠What Can You Do?

Simply ask your AI assistant in natural language:

💬 "Why is my pod crashing?"

• Instant crash diagnosis with logs, events, and resource analysis
• Root cause identification with actionable recommendations

💬 "Deploy a Redis cluster with 3 replicas"

• Creates deployment with best practices
• Configures services, persistent storage, and health checks

💬 "Show me which pods are wasting resources"

• AI-powered cost optimization analysis
• Resource recommendations with potential savings

💬 "Which services can't reach the database?"

• Network connectivity diagnostics with DNS resolution
• Service chain tracing from ingress to pods

💬 "Audit security across all namespaces"

• RBAC permission analysis
• Secret security scanning and pod security policies

26 default tools, 209 with every toolset | 14 workflow prompts | 8 resources + 6 resource templates | Stateless MCP 2026-07-28 | Works with all major AI assistants

⁠Why kubectl-mcp-server?

• 🚀 Stop context-switching - Manage Kubernetes directly from your AI assistant conversations
• 🧠 AI-powered diagnostics - Get intelligent troubleshooting, not just raw data
• 💰 Built-in cost optimization - Identify waste and get actionable savings recommendations
• 🔒 Enterprise-ready - OAuth 2.1 auth with per-tool scopes, read-only mode, Secret redaction, fail-closed network binding
• ⚡ Zero learning curve - Natural language instead of memorizing kubectl commands
• 🌐 Universal compatibility - Works with Claude, Cursor, Windsurf, Copilot, and 15+ other AI tools
• ☸️ Production-grade - Stateless HTTP scales behind any load balancer, Helm chart, 516 passing tests

From debugging crashed pods to optimizing cluster costs, kubectl-mcp-server is your AI-powered DevOps companion.

⁠Live Demos

⁠Claude Desktop

⁠Cursor AI

⁠Windsurf

⁠Installation

⁠Quick Start with npx (Recommended - Zero Install)

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

⁠Or install with pip (Python)

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

⁠Install from GitHub Release

# Install specific version directly from GitHub release (replace {VERSION} with desired version)
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v{VERSION}/kubectl_mcp_server-{VERSION}-py3-none-any.whl

# Example: Install v2.0.0
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v2.0.0/kubectl_mcp_server-2.0.0-py3-none-any.whl

# Or install latest from git
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git

⁠Prerequisites

• Python 3.10+ or uv⁠ (for pip/uvx installation)
• Node.js 18+ (for npx installation)
• kubectl installed and configured
• Access to a Kubernetes cluster

⁠Docker

# Pull from Docker Hub
docker pull rohitghumare64/kubectl-mcp-server:latest

# Or pull from GitHub Container Registry
docker pull ghcr.io/rohitg00/kubectl-mcp-server:latest

# Run with stdio transport (the image runs as UID 10001 with HOME=/home/mcp)
docker run -i --rm -v $HOME/.kube:/home/mcp/.kube:ro rohitghumare64/kubectl-mcp-server:latest

# Run stateless HTTP on localhost only. The container listens on 0.0.0.0, so it refuses
# to start without OAuth (MCP_AUTH_ENABLED) or an explicit MCP_ALLOW_UNAUTHENTICATED=true.
docker run --rm -p 127.0.0.1:8000:8000 -v $HOME/.kube:/home/mcp/.kube:ro \
  -e MCP_ALLOW_UNAUTHENTICATED=true \
  rohitghumare64/kubectl-mcp-server:latest --transport http

⁠Getting Started

⁠1. Test the Server (Optional)

Before integrating with your AI assistant, verify the installation:

# Check if kubectl is configured
kubectl cluster-info

# Test the MCP server directly
kubectl-mcp-server info

# List all available tools
kubectl-mcp-server tools

# Try calling a tool
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

⁠2. Connect to Your AI Assistant

Choose your favorite AI assistant and add the configuration:

⁠Quick Setup with Your AI Assistant

⁠Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠Cursor AI

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠Windsurf

Add to ~/.config/windsurf/mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠Using Python Instead of npx

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

More integrations: GitHub Copilot, Goose, Gemini CLI, Roo Code, and 15+ other clients⁠ —> see full configuration guide⁠ below.

⁠3. Restart Your AI Assistant

After adding the configuration, restart your AI assistant (GitHub Copilot, Claude Code,Claude Desktop, Cursor, etc.) to load the MCP server.

⁠4. Try These Commands

Start a conversation with your AI assistant and try these:

Troubleshooting:

"Show me all pods in the kube-system namespace"
"Why is the nginx-deployment pod crashing?"
"Diagnose network connectivity issues in the default namespace"

Deployments:

"Create a deployment for nginx with 3 replicas"
"Scale my frontend deployment to 5 replicas"
"Roll back the api-server deployment to the previous version"

Cost & Optimization:

"Which pods are using the most resources?"
"Show me idle resources that are wasting money"
"Analyze cost optimization opportunities in the production namespace"

Security:

"Audit RBAC permissions in all namespaces"
"Check for insecure secrets and configurations"
"Show me pods running with privileged access"

Helm:

"List all Helm releases in the cluster"
"Install Redis from the Bitnami chart repository"
"Show me the values for my nginx-ingress Helm release"

Multi-Cluster:

"List all available Kubernetes contexts"
"Switch to the production cluster context"
"Show me cluster information and version"

⁠MCP Client Compatibility

Works seamlessly with all MCP-compatible AI assistants:

⁠All Supported AI Assistants

⁠Claude Code

Add to ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠GitHub Copilot (VS Code)

Add to VS Code settings.json:

{
  "mcp": {
    "servers": {
      "kubernetes": {
        "command": "npx",
        "args": ["-y", "kubectl-mcp-server"]
      }
    }
  }
}

⁠Goose

Add to ~/.config/goose/config.yaml:

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubectl-mcp-server

⁠Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠Roo Code / Kilo Code

Add to ~/.config/roo-code/mcp.json or ~/.config/kilo-code/mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

⁠Complete Feature Set

⁠Toolsets

Every tool definition costs context on every request, and models pick tools less reliably as the list grows. The server therefore registers only the core and helm toolsets (26 tools) by default. kubectl_get, kubectl_describe, kubectl_logs, kubectl_apply and friends work for every resource kind, including custom resources, so the default set covers most day-to-day work. Everything else is opt-in; tools outside the enabled toolsets are not registered at all, so they cannot be called.

kubectl-mcp-server                                    # core + helm
kubectl-mcp-server --toolsets default,diagnostics,certs
kubectl-mcp-server --toolsets all                     # all 209 tools
MCP_TOOLSETS=default,gitops kubectl-mcp-server        # same, via environment

detect_ecosystem reports which operators are installed and which toolsets cover them. With many toolsets enabled and a client that cannot search tools itself, add --tool-search (MCP_TOOL_SEARCH=true): the server then lists only the default tools plus search_tools and call_tool, and the rest are discovered on demand. Read-only mode, scopes and redaction still apply to every discovered call.

For deep work in one ecosystem, its project-maintained MCP server is usually a better fit than the opt-in toolset:

⁠MCP Resources

Access Kubernetes data as browsable resources:

⁠MCP Prompts

Pre-built workflow prompts for common Kubernetes operations:

Add your own prompts in ~/.config/kubectl-mcp/prompts.toml; same-named prompts override the built-ins.

⁠Key Capabilities

• 🤖 26 default tools, 209 opt-in - Generic kubectl and Helm by default, ecosystem toolsets on demand
• 🎯 14 Workflow Prompts - Pre-built workflows for common operations
• 📊 8 Resources + 6 Templates - Browsable Kubernetes data exposure
• 🔄 Opt-in ecosystem toolsets - GitOps, cert-manager, policy, Velero, KEDA, Cilium, Rollouts, CAPI, KubeVirt, Istio, kind, vCluster
• ⚡ Stateless MCP 2026-07-28 - stdio and Streamable HTTP, older clients negotiated automatically
• 🔐 Security First - Read-only mode, per-call confirmation, Secret redaction, flag-injection guard
• 🏥 Advanced Diagnostics - AI-powered troubleshooting and cost optimization
• ☸️ Multi-Cluster - Target any cluster via context parameter in every tool
• 🎡 Full Helm v3 - Complete chart lifecycle management
• 🔧 Powerful CLI - Shell-friendly tool discovery and direct calling
• 🐳 Cloud Native - Deploy in-cluster with kMCP or kagent

⁠Using the CLI

The built-in CLI lets you explore and test tools without an AI assistant:

# List all tools with descriptions
kubectl-mcp-server tools -d

# Search for pod-related tools
kubectl-mcp-server grep "*pod*"

# Show specific tool schema
kubectl-mcp-server tools kubectl_get

# Call a tool directly
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

# Pipe JSON from stdin
echo '{"resource_type": "pods"}' | kubectl-mcp-server call kubectl_get

# Check dependencies
kubectl-mcp-server doctor

# Show/switch Kubernetes context
kubectl-mcp-server context
kubectl-mcp-server context minikube

# List resources and prompts
kubectl-mcp-server resources
kubectl-mcp-server prompts

# Show server info
kubectl-mcp-server info

⁠CLI Features

• Structured errors: Actionable error messages with suggestions
• Colorized output: Human-readable with JSON mode for scripting (--json)
• NO_COLOR support: Respects NO_COLOR environment variable
• Stdin support: Pipe JSON arguments to commands

⁠Advanced Configuration

⁠Transport Modes

# stdio (default) - Claude Desktop, Cursor, Windsurf, Claude Code
kubectl-mcp-server

# Streamable HTTP, stateless, at http://127.0.0.1:8000/mcp
kubectl-mcp-server --transport http --port 8000

# SSE - deprecated by the