MCP server for Kubernetes clusters

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, manage Helm charts, and visualize dashboards, 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)

# Standard installation
pip install kubectl-mcp-server

# With interactive UI dashboards (recommended)
pip install kubectl-mcp-server[ui]

---

📑 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
• Optional Features
  • Interactive Dashboards
  • Browser Automation
• Enterprise
• 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

💬 "Show me the cluster dashboard"

• Interactive HTML dashboards with live metrics
• Visual timeline of events and resource usage

253 powerful tools | 8 workflow prompts | 8 data resources | 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, RBAC validation, non-destructive mode, secret masking
• ⚡ Zero learning curve - Natural language instead of memorizing kubectl commands
• 🌐 Universal compatibility - Works with Claude, Cursor, Windsurf, Copilot, and 15+ other AI tools
• 📊 Visual insights - Interactive dashboards and browser automation for web-based tools
• ☸️ Production-grade - Deploy in-cluster with kMCP, 216 passing tests, active maintenance

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)

# Standard installation
pip install kubectl-mcp-server

# With interactive UI dashboards (recommended)
pip install kubectl-mcp-server[ui]

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 v1.19.0
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v1.19.0/kubectl_mcp_server-1.19.0-py3-none-any.whl

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

Prerequisites

• Python 3.9+ (for pip installation)
• Node.js 14+ (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
docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest

# Run with HTTP transport
docker run -p 8000:8000 -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest --transport sse

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 get_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:

Client	Status	Client	Status
Claude Desktop	✅ Native	Claude Code	✅ Native
Cursor	✅ Native	Windsurf	✅ Native
GitHub Copilot	✅ Native	OpenAI Codex	✅ Native
Gemini CLI	✅ Native	Goose	✅ Native
Roo Code	✅ Native	Kilo Code	✅ Native
Amp	✅ Native	Trae	✅ Native
OpenCode	✅ Native	Kiro CLI	✅ Native
Antigravity	✅ Native	Clawdbot	✅ Native
Droid (Factory)	✅ Native	Any MCP Client	✅ Compatible

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

253 MCP Tools for Complete Kubernetes Management

Category	Tools
Pods	get_pods, get_logs, get_pod_events, check_pod_health, exec_in_pod, cleanup_pods, get_pod_conditions, get_previous_logs
Deployments	get_deployments, create_deployment, scale_deployment, kubectl_rollout, restart_deployment
Workloads	get_statefulsets, get_daemonsets, get_jobs, get_replicasets
Services & Networking	get_services, get_ingress, get_endpoints, diagnose_network_connectivity, check_dns_resolution, trace_service_chain
Storage	get_persistent_volumes, get_pvcs, get_storage_classes
Config	get_configmaps, get_secrets, get_resource_quotas, get_limit_ranges
Cluster	get_nodes, get_namespaces, get_cluster_info, get_cluster_version, health_check, get_node_metrics, get_pod_metrics
RBAC & Security	get_rbac_roles, get_cluster_roles, get_service_accounts, audit_rbac_permissions, check_secrets_security, get_pod_security_info, get_admission_webhooks
CRDs	get_crds, get_priority_classes
Helm Releases	helm_list, helm_status, helm_history, helm_get_values, helm_get_manifest, helm_get_notes, helm_get_hooks, helm_get_all
Helm Charts	helm_show_chart, helm_show_values, helm_show_readme, helm_show_crds, helm_show_all, helm_search_repo, helm_search_hub
Helm Repos	helm_repo_list, helm_repo_add, helm_repo_remove, helm_repo_update
Helm Operations	install_helm_chart, upgrade_helm_chart, uninstall_helm_chart, helm_rollback, helm_test, helm_template, helm_template_apply
Helm Development	helm_create, helm_lint, helm_package, helm_pull, helm_dependency_list, helm_dependency_update, helm_dependency_build, helm_version, helm_env
Context	get_current_context, switch_context, list_contexts, list_kubeconfig_contexts
Diagnostics	diagnose_pod_crash, detect_pending_pods, get_evicted_pods, compare_namespaces
Operations	kubectl_apply, kubectl_create, kubectl_describe, kubectl_patch, delete_resource, kubectl_cp, backup_resource, label_resource, annotate_resource, taint_node, wait_for_condition
Autoscaling	get_hpa, get_pdb
Cost Optimization	get_resource_recommendations, get_idle_resources, get_resource_quotas_usage, get_cost_analysis, get_overprovisioned_resources, get_resource_trends, get_namespace_cost_allocation, optimize_resource_requests
Advanced	kubectl_generic, kubectl_explain, get_api_resources, port_forward, get_resource_usage, node_management
UI Dashboards	show_pod_logs_ui, show_pods_dashboard_ui, show_resource_yaml_ui, show_cluster_overview_ui, show_events_timeline_ui, render_k8s_dashboard_screenshot
GitOps (Flux/Argo)	gitops_apps_list, gitops_app_get, gitops_app_sync, gitops_app_status, gitops_sources_list, gitops_source_get, gitops_detect_engine
Cert-Manager	certs_list, certs_get, certs_issuers_list, certs_issuer_get, certs_renew, certs_status_explain, certs_challenges_list, certs_requests_list, certs_detect
Policy (Kyverno/Gatekeeper)	policy_list, policy_get, policy_violations_list, policy_explain_denial, policy_audit, policy_detect
Backup (Velero)	backup_list, backup_get, backup_create, backup_delete, restore_list, restore_create, restore_get, backup_locations_list, backup_schedules_list, backup_schedule_create, backup_detect
KEDA Autoscaling	keda_scaledobjects_list, keda_scaledobject_get, keda_scaledjobs_list, keda_triggerauths_list, keda_triggerauth_get, keda_hpa_list, keda_detect
Cilium/Hubble	cilium_policies_list, cilium_policy_get, cilium_endpoints_list, cilium_identities_list, cilium_nodes_list, cilium_status, hubble_flows_query, cilium_detect
Argo Rollouts/Flagger	rollouts_list, rollout_get, rollout_status, rollout_promote, rollout_abort, rollout_retry, rollout_restart, analysis_runs_list, flagger_canaries_list, flagger_canary_get, rollouts_detect
Cluster API	capi_clusters_list, capi_cluster_get, capi_machines_list, capi_machine_get, capi_machinedeployments_list, capi_machinedeployment_scale, capi_machinesets_list, capi_machinehealthchecks_list, capi_clusterclasses_list, capi_cluster_kubeconfig, capi_detect
KubeVirt VMs	kubevirt_vms_list, kubevirt_vm_get, kubevirt_vmis_list, kubevirt_vm_start, kubevirt_vm_stop, kubevirt_vm_restart, kubevirt_vm_pause, kubevirt_vm_unpause, kubevirt_vm_migrate, kubevirt_datasources_list, kubevirt_instancetypes_list, kubevirt_datavolumes_list, kubevirt_detect
Istio/Kiali	istio_virtualservices_list, istio_virtualservice_get, istio_destinationrules_list, istio_gateways_list, istio_peerauthentications_list, istio_authorizationpolicies_list, istio_proxy_status, istio_analyze, istio_sidecar_status, istio_detect
vCluster (vind)	vind_detect_tool, vind_list_clusters_tool, vind_status_tool, vind_get_kubeconfig_tool, vind_logs_tool, vind_create_cluster_tool, vind_delete_cluster_tool, vind_pause_tool, vind_resume_tool, vind_connect_tool, vind_disconnect_tool, vind_upgrade_tool, vind_describe_tool, vind_platform_start_tool
kind (K8s in Docker)	kind_detect_tool, kind_version_tool, kind_list_clusters_tool, kind_get_nodes_tool, kind_get_kubeconfig_tool, kind_export_logs_tool, kind_cluster_info_tool, kind_node_labels_tool, kind_create_cluster_tool, kind_delete_cluster_tool, kind_delete_all_clusters_tool, kind_load_image_tool, kind_load_image_archive_tool, kind_build_node_image_tool, kind_set_kubeconfig_tool

MCP Resources

Access Kubernetes data as browsable resources:

Resource URI	Description
kubeconfig://contexts	List all available kubectl contexts
kubeconfig://current-context	Get current active context
namespace://current	Get current namespace
namespace://list	List all namespaces
cluster://info	Get cluster information
cluster://nodes	Get detailed node information
cluster://version	Get Kubernetes version
cluster://api-resources	List available API resources
manifest://deployments/{ns}/{name}	Get deployment YAML
manifest://services/{ns}/{name}	Get service YAML
manifest://pods/{ns}/{name}	Get pod YAML
manifest://configmaps/{ns}/{name}	Get ConfigMap YAML
manifest://secrets/{ns}/{name}	Get secret YAML (data masked)
manifest://ingresses/{ns}/{name}	Get ingress YAML

MCP Prompts

Pre-built workflow prompts for common Kubernetes operations:

Prompt	Description
troubleshoot_workload	Comprehensive troubleshooting guide for pods/deployments
deploy_application	Step-by-step deployment workflow
security_audit	Security scanning and RBAC analysis workflow
cost_optimization	Resource optimization and cost analysis workflow
disaster_recovery	Backup and recovery planning workflow
debug_networking	Network debugging for services and connectivity
scale_application	Scaling guide with HPA/VPA best practices
upgrade_cluster	Kubernetes cluster upgrade planning

Key Capabilities

• 🤖 253 Powerful Tools - Complete Kubernetes management from pods to security
• 🎯 8 AI Workflow Prompts - Pre-built workflows for common operations
• 📊 8 MCP Resources - Browsable Kubernetes data exposure
• 🎨 6 Interactive Dashboards - HTML UI tools for visual cluster management
• 🌐 26 Browser Tools - Web automation with cloud provider support
• 🔄 107 Ecosystem Tools - GitOps, Cert-Manager, Policy, Backup, KEDA, Cilium, Rollouts, CAPI, KubeVirt, Istio, vCluster
• ⚡ Multi-Transport - stdio, SSE, HTTP, streamable-http
• 🔐 Security First - Non-destructive mode, secret masking, RBAC validation
• 🏥 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 get_pods

# Call a tool directly
kubectl-mcp-server call get_pods '{"namespace": "kube-system"}'

# Pipe JSON from stdin
echo '{"namespace": "default"}' | kubectl-mcp-server call get_pods

# 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

The server supports multiple transport protocols:

# stdio (default) - Best for Claude Desktop, Cursor, Windsurf
kubectl-mcp-server
# or: python -m kubectl_mcp_tool.mcp_server

# SSE - Server-Sent Events for web clients
kubectl-mcp-server --transport sse --port 8000

# HTTP - Standard HTTP for REST clients
kubectl-mcp-server --transport http --port 8000

# streamable-http - For agentgateway integration
kubectl-mcp-server --transport streamable-http --port 8000

Transport Options:

• --transport: Choose from stdio, sse, http, streamable-http (default: stdio)
• --host: Bind address (default: 0.0.0.0)
• --port: Port for network transports (default: 8000)
• --disable-destructive (or --non-destructive): Block destructive operations (allow create/update, block delete)
• --read-only: Block all write operations

Environment Variables

Core Settings:

Variable	Description	Default
KUBECONFIG	Path to kubeconfig file	~/.kube/config
MCP_DEBUG	Enable verbose logging	false
MCP_LOG_FILE	Log file path	None (stdout)

Authentication (Enterprise):

Variable	Description	Default
MCP_AUTH_ENABLED	Enable OAuth 2.1 authentication	false
MCP_AUTH_ISSUER	OAuth 2.0 Authorization Server URL	-
`MCP_AUTH_