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. - What Can You Do? - Why kubectl-mcp-server? - Live Demos - Installation - Quick St
Add this skill
npx mdskills install rohitg00/kubectl-mcp-serverComprehensive K8s MCP server with 253 tools, natural language diagnostics, and multi-client support
1<p align="center">2 <img src="logos/kubectl-mcp-server-icon.svg" alt="kubectl-mcp-server logo" width="80" height="80">3 <br>4 <strong style="font-size: 24px;">kubectl-mcp-server</strong>5</p>67<p align="center">8<b>Control your entire Kubernetes infrastructure through natural language conversations with AI.</b><br>9Talk 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.10</p>1112<p align="center">13 <a href="https://github.com/rohitg00/kubectl-mcp-server"><img src="https://img.shields.io/github/stars/rohitg00/kubectl-mcp-server?style=flat&logo=github" alt="GitHub Stars"></a>14 <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>15 <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python"></a>16 <a href="https://kubernetes.io/"><img src="https://img.shields.io/badge/kubernetes-%23326ce5.svg?style=flat&logo=kubernetes&logoColor=white" alt="Kubernetes"></a>17 <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP"></a>18</p>1920<p align="center">21 <a href="https://pypi.org/project/kubectl-mcp-server/"><img src="https://img.shields.io/pypi/v/kubectl-mcp-server?color=blue&label=PyPI" alt="PyPI"></a>22 <a href="https://www.npmjs.com/package/kubectl-mcp-server"><img src="https://img.shields.io/npm/v/kubectl-mcp-server?color=green&label=npm" alt="npm"></a>23 <a href="https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server"><img src="https://img.shields.io/docker/pulls/rohitghumare64/kubectl-mcp-server.svg" alt="Docker"></a>24 <a href="https://github.com/rohitg00/kubectl-mcp-server"><img src="https://img.shields.io/badge/tests-234%20passed-success"25 <a href="https://deepwiki.com/rohitg00/kubectl-mcp-server"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>26 <a href="https://aregistry.ai"><img src="https://img.shields.io/badge/agentregistry-verified-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiIHZpZXdCb3g9IjAgMCAxNiAxNiI+PHBhdGggZD0iTTE1Ljk5MiA2LjAzN2wtMy4wMjEtLjQzOS0xLjM1LTIuNzM2Yy0uMzQ2LS43MDItMS41MDQtLjcwMi0xLjg1IDBMOC40MjEgNS41OTggNS40IDYuMDM3Yy0uNzc2LjExMy0xLjA4OCAxLjA1My0uNTI4IDEuNTkzbDIuMTg2IDIuMTI5LS41MTYgMy4wMWMtLjEzMy43NzUuNjgyIDEuMzY2IDEuMzc4Ljk5OGwyLjcwMi0xLjQyIDIuNzAyIDEuNDJjLjY5Ni4zNjggMS41MTEtLjIyMyAxLjM3OC0uOTk4bC0uNTE2LTMuMDEgMi4xODYtMi4xMjljLjU2LS41NCAwLjI0OC0xLjQ4LS41MjgtMS41OTN6Ii8+PC9zdmc+" alt="agentregistry"></a>27</p>2829---3031## Installation3233### Quick Start with npx (Recommended - Zero Install)3435```bash36# Run directly without installation - works instantly!37npx -y kubectl-mcp-server3839# Or install globally for faster startup40npm install -g kubectl-mcp-server41```4243### Or install with pip (Python)4445```bash46# Standard installation47pip install kubectl-mcp-server4849# With interactive UI dashboards (recommended)50pip install kubectl-mcp-server[ui]51```52---5354## 📑 Table of Contents5556- [What Can You Do?](#what-can-you-do)57- [Why kubectl-mcp-server?](#why-kubectl-mcp-server)58- [Live Demos](#live-demos)59- [Installation](#installation)60 - [Quick Start with npx](#quick-start-with-npx-recommended---zero-install)61 - [Install with pip](#or-install-with-pip-python)62 - [Docker](#docker)63- [Getting Started](#getting-started)64- [Quick Setup with Your AI Assistant](#quick-setup-with-your-ai-assistant)65- [All Supported AI Assistants](#all-supported-ai-assistants)66- [Complete Feature Set](#complete-feature-set)67- [Using the CLI](#using-the-cli)68- [Advanced Configuration](#advanced-configuration)69- [Optional Features](#optional-interactive-dashboards-6-ui-tools)70 - [Interactive Dashboards](#optional-interactive-dashboards-6-ui-tools)71 - [Browser Automation](#optional-browser-automation-26-tools)72- [Enterprise](#enterprise-oauth-21-authentication)73- [Integrations & Ecosystem](#integrations--ecosystem)74- [In-Cluster Deployment](#in-cluster-deployment)75- [Multi-Cluster Support](#multi-cluster-support)76- [Architecture](#architecture)77- [Agent Skills](#agent-skills-24-skills-for-ai-coding-agents)78- [Development & Testing](#development--testing)79- [Contributing](#contributing)80- [Support & Community](#support--community)8182---8384## What Can You Do?8586Simply ask your AI assistant in natural language:8788💬 **"Why is my pod crashing?"**89- Instant crash diagnosis with logs, events, and resource analysis90- Root cause identification with actionable recommendations9192💬 **"Deploy a Redis cluster with 3 replicas"**93- Creates deployment with best practices94- Configures services, persistent storage, and health checks9596💬 **"Show me which pods are wasting resources"**97- AI-powered cost optimization analysis98- Resource recommendations with potential savings99100💬 **"Which services can't reach the database?"**101- Network connectivity diagnostics with DNS resolution102- Service chain tracing from ingress to pods103104💬 **"Audit security across all namespaces"**105- RBAC permission analysis106- Secret security scanning and pod security policies107108💬 **"Show me the cluster dashboard"**109- Interactive HTML dashboards with live metrics110- Visual timeline of events and resource usage111112**253 powerful tools** | **8 workflow prompts** | **8 data resources** | **Works with all major AI assistants**113114## Why kubectl-mcp-server?115116- **🚀 Stop context-switching** - Manage Kubernetes directly from your AI assistant conversations117- **🧠 AI-powered diagnostics** - Get intelligent troubleshooting, not just raw data118- **💰 Built-in cost optimization** - Identify waste and get actionable savings recommendations119- **🔒 Enterprise-ready** - OAuth 2.1 auth, RBAC validation, non-destructive mode, secret masking120- **⚡ Zero learning curve** - Natural language instead of memorizing kubectl commands121- **🌐 Universal compatibility** - Works with Claude, Cursor, Windsurf, Copilot, and 15+ other AI tools122- **📊 Visual insights** - Interactive dashboards and browser automation for web-based tools123- **☸️ Production-grade** - Deploy in-cluster with kMCP, 216 passing tests, active maintenance124125From debugging crashed pods to optimizing cluster costs, kubectl-mcp-server is your AI-powered DevOps companion.126127## Live Demos128129### Claude Desktop130131132### Cursor AI133134135### Windsurf136137138## Installation139140### Quick Start with npx (Recommended - Zero Install)141142```bash143# Run directly without installation - works instantly!144npx -y kubectl-mcp-server145146# Or install globally for faster startup147npm install -g kubectl-mcp-server148```149150### Or install with pip (Python)151152```bash153# Standard installation154pip install kubectl-mcp-server155156# With interactive UI dashboards (recommended)157pip install kubectl-mcp-server[ui]158```159160### Install from GitHub Release161162```bash163# Install specific version directly from GitHub release (replace {VERSION} with desired version)164pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v{VERSION}/kubectl_mcp_server-{VERSION}-py3-none-any.whl165166# Example: Install v1.19.0167pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v1.19.0/kubectl_mcp_server-1.19.0-py3-none-any.whl168169# Or install latest from git170pip install git+https://github.com/rohitg00/kubectl-mcp-server.git171```172173### Prerequisites174- **Python 3.9+** (for pip installation)175- **Node.js 14+** (for npx installation)176- **kubectl** installed and configured177- Access to a Kubernetes cluster178179### Docker180181```bash182# Pull from Docker Hub183docker pull rohitghumare64/kubectl-mcp-server:latest184185# Or pull from GitHub Container Registry186docker pull ghcr.io/rohitg00/kubectl-mcp-server:latest187188# Run with stdio transport189docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest190191# Run with HTTP transport192docker run -p 8000:8000 -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest --transport sse193```194195## Getting Started196197### 1. Test the Server (Optional)198199Before integrating with your AI assistant, verify the installation:200201```bash202# Check if kubectl is configured203kubectl cluster-info204205# Test the MCP server directly206kubectl-mcp-server info207208# List all available tools209kubectl-mcp-server tools210211# Try calling a tool212kubectl-mcp-server call get_pods '{"namespace": "kube-system"}'213```214215### 2. Connect to Your AI Assistant216217Choose your favorite AI assistant and add the configuration:218219## Quick Setup with Your AI Assistant220221### Claude Desktop222223Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:224225```json226{227 "mcpServers": {228 "kubernetes": {229 "command": "npx",230 "args": ["-y", "kubectl-mcp-server"]231 }232 }233}234```235236### Cursor AI237238Add to `~/.cursor/mcp.json`:239240```json241{242 "mcpServers": {243 "kubernetes": {244 "command": "npx",245 "args": ["-y", "kubectl-mcp-server"]246 }247 }248}249```250251### Windsurf252253Add to `~/.config/windsurf/mcp.json`:254255```json256{257 "mcpServers": {258 "kubernetes": {259 "command": "npx",260 "args": ["-y", "kubectl-mcp-server"]261 }262 }263}264```265266### Using Python Instead of npx267268```json269{270 "mcpServers": {271 "kubernetes": {272 "command": "python",273 "args": ["-m", "kubectl_mcp_tool.mcp_server"],274 "env": {275 "KUBECONFIG": "/path/to/.kube/config"276 }277 }278 }279}280```281282**More integrations**: GitHub Copilot, Goose, Gemini CLI, Roo Code, and [15+ other clients](#mcp-client-compatibility) —> see [full configuration guide](#all-supported-ai-assistants) below.283284### 3. Restart Your AI Assistant285286After adding the configuration, restart your AI assistant **(GitHub Copilot, Claude Code,Claude Desktop, Cursor, etc.)** to load the MCP server.287288### 4. Try These Commands289290Start a conversation with your AI assistant and try these:291292**Troubleshooting:**293```294"Show me all pods in the kube-system namespace"295"Why is the nginx-deployment pod crashing?"296"Diagnose network connectivity issues in the default namespace"297```298299**Deployments:**300```301"Create a deployment for nginx with 3 replicas"302"Scale my frontend deployment to 5 replicas"303"Roll back the api-server deployment to the previous version"304```305306**Cost & Optimization:**307```308"Which pods are using the most resources?"309"Show me idle resources that are wasting money"310"Analyze cost optimization opportunities in the production namespace"311```312313**Security:**314```315"Audit RBAC permissions in all namespaces"316"Check for insecure secrets and configurations"317"Show me pods running with privileged access"318```319320**Helm:**321```322"List all Helm releases in the cluster"323"Install Redis from the Bitnami chart repository"324"Show me the values for my nginx-ingress Helm release"325```326327**Multi-Cluster:**328```329"List all available Kubernetes contexts"330"Switch to the production cluster context"331"Show me cluster information and version"332```333334## MCP Client Compatibility335336Works seamlessly with **all MCP-compatible AI assistants**:337338| Client | Status | Client | Status |339|--------|--------|--------|--------|340| Claude Desktop | ✅ Native | Claude Code | ✅ Native |341| Cursor | ✅ Native | Windsurf | ✅ Native |342| GitHub Copilot | ✅ Native | OpenAI Codex | ✅ Native |343| Gemini CLI | ✅ Native | Goose | ✅ Native |344| Roo Code | ✅ Native | Kilo Code | ✅ Native |345| Amp | ✅ Native | Trae | ✅ Native |346| OpenCode | ✅ Native | Kiro CLI | ✅ Native |347| Antigravity | ✅ Native | Clawdbot | ✅ Native |348| Droid (Factory) | ✅ Native | Any MCP Client | ✅ Compatible |349350## All Supported AI Assistants351352### Claude Code353354Add to `~/.config/claude-code/mcp.json`:355356```json357{358 "mcpServers": {359 "kubernetes": {360 "command": "npx",361 "args": ["-y", "kubectl-mcp-server"]362 }363 }364}365```366367### GitHub Copilot (VS Code)368369Add to VS Code `settings.json`:370371```json372{373 "mcp": {374 "servers": {375 "kubernetes": {376 "command": "npx",377 "args": ["-y", "kubectl-mcp-server"]378 }379 }380 }381}382```383384### Goose385386Add to `~/.config/goose/config.yaml`:387388```yaml389extensions:390 kubernetes:391 command: npx392 args:393 - -y394 - kubectl-mcp-server395```396397### Gemini CLI398399Add to `~/.gemini/settings.json`:400401```json402{403 "mcpServers": {404 "kubernetes": {405 "command": "npx",406 "args": ["-y", "kubectl-mcp-server"]407 }408 }409}410```411412### Roo Code / Kilo Code413414Add to `~/.config/roo-code/mcp.json` or `~/.config/kilo-code/mcp.json`:415416```json417{418 "mcpServers": {419 "kubernetes": {420 "command": "npx",421 "args": ["-y", "kubectl-mcp-server"]422 }423 }424}425```426427## Complete Feature Set428429### 253 MCP Tools for Complete Kubernetes Management430431| Category | Tools |432|----------|-------|433| **Pods** | `get_pods`, `get_logs`, `get_pod_events`, `check_pod_health`, `exec_in_pod`, `cleanup_pods`, `get_pod_conditions`, `get_previous_logs` |434| **Deployments** | `get_deployments`, `create_deployment`, `scale_deployment`, `kubectl_rollout`, `restart_deployment` |435| **Workloads** | `get_statefulsets`, `get_daemonsets`, `get_jobs`, `get_replicasets` |436| **Services & Networking** | `get_services`, `get_ingress`, `get_endpoints`, `diagnose_network_connectivity`, `check_dns_resolution`, `trace_service_chain` |437| **Storage** | `get_persistent_volumes`, `get_pvcs`, `get_storage_classes` |438| **Config** | `get_configmaps`, `get_secrets`, `get_resource_quotas`, `get_limit_ranges` |439| **Cluster** | `get_nodes`, `get_namespaces`, `get_cluster_info`, `get_cluster_version`, `health_check`, `get_node_metrics`, `get_pod_metrics` |440| **RBAC & Security** | `get_rbac_roles`, `get_cluster_roles`, `get_service_accounts`, `audit_rbac_permissions`, `check_secrets_security`, `get_pod_security_info`, `get_admission_webhooks` |441| **CRDs** | `get_crds`, `get_priority_classes` |442| **Helm Releases** | `helm_list`, `helm_status`, `helm_history`, `helm_get_values`, `helm_get_manifest`, `helm_get_notes`, `helm_get_hooks`, `helm_get_all` |443| **Helm Charts** | `helm_show_chart`, `helm_show_values`, `helm_show_readme`, `helm_show_crds`, `helm_show_all`, `helm_search_repo`, `helm_search_hub` |444| **Helm Repos** | `helm_repo_list`, `helm_repo_add`, `helm_repo_remove`, `helm_repo_update` |445| **Helm Operations** | `install_helm_chart`, `upgrade_helm_chart`, `uninstall_helm_chart`, `helm_rollback`, `helm_test`, `helm_template`, `helm_template_apply` |446| **Helm Development** | `helm_create`, `helm_lint`, `helm_package`, `helm_pull`, `helm_dependency_list`, `helm_dependency_update`, `helm_dependency_build`, `helm_version`, `helm_env` |447| **Context** | `get_current_context`, `switch_context`, `list_contexts`, `list_kubeconfig_contexts` |448| **Diagnostics** | `diagnose_pod_crash`, `detect_pending_pods`, `get_evicted_pods`, `compare_namespaces` |449| **Operations** | `kubectl_apply`, `kubectl_create`, `kubectl_describe`, `kubectl_patch`, `delete_resource`, `kubectl_cp`, `backup_resource`, `label_resource`, `annotate_resource`, `taint_node`, `wait_for_condition` |450| **Autoscaling** | `get_hpa`, `get_pdb` |451| **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` |452| **Advanced** | `kubectl_generic`, `kubectl_explain`, `get_api_resources`, `port_forward`, `get_resource_usage`, `node_management` |453| **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` |454| **GitOps (Flux/Argo)** | `gitops_apps_list`, `gitops_app_get`, `gitops_app_sync`, `gitops_app_status`, `gitops_sources_list`, `gitops_source_get`, `gitops_detect_engine` |455| **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` |456| **Policy (Kyverno/Gatekeeper)** | `policy_list`, `policy_get`, `policy_violations_list`, `policy_explain_denial`, `policy_audit`, `policy_detect` |457| **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` |458| **KEDA Autoscaling** | `keda_scaledobjects_list`, `keda_scaledobject_get`, `keda_scaledjobs_list`, `keda_triggerauths_list`, `keda_triggerauth_get`, `keda_hpa_list`, `keda_detect` |459| **Cilium/Hubble** | `cilium_policies_list`, `cilium_policy_get`, `cilium_endpoints_list`, `cilium_identities_list`, `cilium_nodes_list`, `cilium_status`, `hubble_flows_query`, `cilium_detect` |460| **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` |461| **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` |462| **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` |463| **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` |464| **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` |465| **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` |466467### MCP Resources468469Access Kubernetes data as browsable resources:470471| Resource URI | Description |472|--------------|-------------|473| `kubeconfig://contexts` | List all available kubectl contexts |474| `kubeconfig://current-context` | Get current active context |475| `namespace://current` | Get current namespace |476| `namespace://list` | List all namespaces |477| `cluster://info` | Get cluster information |478| `cluster://nodes` | Get detailed node information |479| `cluster://version` | Get Kubernetes version |480| `cluster://api-resources` | List available API resources |481| `manifest://deployments/{ns}/{name}` | Get deployment YAML |482| `manifest://services/{ns}/{name}` | Get service YAML |483| `manifest://pods/{ns}/{name}` | Get pod YAML |484| `manifest://configmaps/{ns}/{name}` | Get ConfigMap YAML |485| `manifest://secrets/{ns}/{name}` | Get secret YAML (data masked) |486| `manifest://ingresses/{ns}/{name}` | Get ingress YAML |487488### MCP Prompts489490Pre-built workflow prompts for common Kubernetes operations:491492| Prompt | Description |493|--------|-------------|494| `troubleshoot_workload` | Comprehensive troubleshooting guide for pods/deployments |495| `deploy_application` | Step-by-step deployment workflow |496| `security_audit` | Security scanning and RBAC analysis workflow |497| `cost_optimization` | Resource optimization and cost analysis workflow |498| `disaster_recovery` | Backup and recovery planning workflow |499| `debug_networking` | Network debugging for services and connectivity |500| `scale_application` | Scaling guide with HPA/VPA best practices |501| `upgrade_cluster` | Kubernetes cluster upgrade planning |502503### Key Capabilities504505- 🤖 **253 Powerful Tools** - Complete Kubernetes management from pods to security506- 🎯 **8 AI Workflow Prompts** - Pre-built workflows for common operations507- 📊 **8 MCP Resources** - Browsable Kubernetes data exposure508- 🎨 **6 Interactive Dashboards** - HTML UI tools for visual cluster management509- 🌐 **26 Browser Tools** - Web automation with cloud provider support510- 🔄 **107 Ecosystem Tools** - GitOps, Cert-Manager, Policy, Backup, KEDA, Cilium, Rollouts, CAPI, KubeVirt, Istio, vCluster511- ⚡ **Multi-Transport** - stdio, SSE, HTTP, streamable-http512- 🔐 **Security First** - Non-destructive mode, secret masking, RBAC validation513- 🏥 **Advanced Diagnostics** - AI-powered troubleshooting and cost optimization514- ☸️ **Multi-Cluster** - Target any cluster via context parameter in every tool515- 🎡 **Full Helm v3** - Complete chart lifecycle management516- 🔧 **Powerful CLI** - Shell-friendly tool discovery and direct calling517- 🐳 **Cloud Native** - Deploy in-cluster with kMCP or kagent518519## Using the CLI520521The built-in CLI lets you explore and test tools without an AI assistant:522523```bash524# List all tools with descriptions525kubectl-mcp-server tools -d526527# Search for pod-related tools528kubectl-mcp-server grep "*pod*"529530# Show specific tool schema531kubectl-mcp-server tools get_pods532533# Call a tool directly534kubectl-mcp-server call get_pods '{"namespace": "kube-system"}'535536# Pipe JSON from stdin537echo '{"namespace": "default"}' | kubectl-mcp-server call get_pods538539# Check dependencies540kubectl-mcp-server doctor541542# Show/switch Kubernetes context543kubectl-mcp-server context544kubectl-mcp-server context minikube545546# List resources and prompts547kubectl-mcp-server resources548kubectl-mcp-server prompts549550# Show server info551kubectl-mcp-server info552```553554### CLI Features555556- **Structured errors**: Actionable error messages with suggestions557- **Colorized output**: Human-readable with JSON mode for scripting (`--json`)558- **NO_COLOR support**: Respects `NO_COLOR` environment variable559- **Stdin support**: Pipe JSON arguments to commands560561## Advanced Configuration562563### Transport Modes564565The server supports multiple transport protocols:566567```bash568# stdio (default) - Best for Claude Desktop, Cursor, Windsurf569kubectl-mcp-server570# or: python -m kubectl_mcp_tool.mcp_server571572# SSE - Server-Sent Events for web clients573kubectl-mcp-server --transport sse --port 8000574575# HTTP - Standard HTTP for REST clients576kubectl-mcp-server --transport http --port 8000577578# streamable-http - For agentgateway integration579kubectl-mcp-server --transport streamable-http --port 8000580```581582**Transport Options:**583- `--transport`: Choose from `stdio`, `sse`, `http`, `streamable-http` (default: `stdio`)584- `--host`: Bind address (default: `0.0.0.0`)585- `--port`: Port for network transports (default: `8000`)586- `--non-destructive`: Enable read-only mode (blocks delete, apply, create operations)587588### Environment Variables589590**Core Settings:**591592| Variable | Description | Default |593|----------|-------------|---------|594| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` |595| `MCP_DEBUG` | Enable verbose logging | `false` |596| `MCP_LOG_FILE` | Log file path | None (stdout) |597598**Authentication (Enterprise):**599600| Variable | Description | Default |601|----------|-------------|---------|602| `MCP_AUTH_ENABLED` | Enable OAuth 2.1 authentication | `false` |603| `MCP_AUTH_ISSUER` | OAuth 2.0 Authorization Server URL | - |604| `MCP_AUTH_JWKS_URI` | JWKS endpoint URL | Auto-derived |605| `MCP_AUTH_AUDIENCE` | Expected token audience | `kubectl-mcp-server` |606| `MCP_AUTH_REQUIRED_SCOPES` | Required OAuth scopes | `mcp:tools` |607608**Browser Automation (Optional):**609610| Variable | Description | Default |611|----------|-------------|---------|612| `MCP_BROWSER_ENABLED` | Enable browser automation tools | `false` |613| `MCP_BROWSER_PROVIDER` | Cloud provider (browserbase/browseruse) | None |614| `MCP_BROWSER_PROFILE` | Persistent profile path | None |615| `MCP_BROWSER_CDP_URL` | Remote CDP WebSocket URL | None |616| `MCP_BROWSER_PROXY` | Proxy server URL | None |617618## Optional: Interactive Dashboards (6 UI Tools)619620Get beautiful HTML dashboards for visual cluster management.621622**Installation:**623624```bash625# Install with UI support626pip install kubectl-mcp-server[ui]627```628629**6 Dashboard Tools:**630- 📊 `show_pods_dashboard_ui` - Real-time pod status table631- 📝 `show_pod_logs_ui` - Interactive log viewer with search632- 🎯 `show_cluster_overview_ui` - Complete cluster dashboard633- ⚡ `show_events_timeline_ui` - Events timeline with filtering634- 📄 `show_resource_yaml_ui` - YAML viewer with syntax highlighting635- 📸 `render_k8s_dashboard_screenshot` - Export dashboards as PNG636637**Features:**638- 🎨 Dark theme optimized for terminals (Catppuccin)639- 🔄 Graceful fallback to JSON for incompatible clients640- 🖼️ Screenshot rendering for universal compatibility641- 🚀 Zero external dependencies642643**Works With**: Goose, LibreChat, Nanobot (full HTML UI) | Claude Desktop, Cursor, others (JSON + screenshots)644645## Optional: Browser Automation (26 Tools)646647Automate web-based Kubernetes operations with [agent-browser](https://github.com/vercel-labs/agent-browser) integration.648649**Quick Setup:**650651```bash652# Install agent-browser653npm install -g agent-browser654agent-browser install655656# Enable browser tools657export MCP_BROWSER_ENABLED=true658kubectl-mcp-server659```660661**What You Can Do:**662- 🌐 Test deployed apps via Ingress URLs663- 📸 Screenshot Grafana, ArgoCD, or any K8s dashboard664- ☁️ Automate cloud console operations (EKS, GKE, AKS)665- 🏥 Health check web applications666- 📄 Export monitoring dashboards as PDF667- 🔐 Test authentication flows with persistent sessions668669**26 Available Tools**: `browser_open`, `browser_screenshot`, `browser_click`, `browser_fill`, `browser_test_ingress`, `browser_screenshot_grafana`, `browser_health_check`, and [19 more](https://github.com/rohitg00/kubectl-mcp-server#browser-tools)670671**Advanced Features**:672- Cloud providers: Browserbase, Browser Use673- Persistent browser profiles674- Remote CDP connections675- Session management676677## Optional: kubectl-mcp-app (8 Interactive UI Dashboards)678679A standalone npm package that provides beautiful, interactive UI dashboards for Kubernetes management using the MCP ext-apps SDK.680681**Installation:**682683```bash684# Via npm685npm install -g kubectl-mcp-app686687# Or via npx (no install)688npx kubectl-mcp-app689```690691**Claude Desktop Configuration:**692693```json694{695 "mcpServers": {696 "kubectl-app": {697 "command": "npx",698 "args": ["kubectl-mcp-app"]699 }700 }701}702```703704**8 Interactive UI Tools:**705706| Tool | Description |707| ---- | ----------- |708| `k8s-pods` | Interactive pod viewer with filtering, sorting, status indicators |709| `k8s-logs` | Real-time log viewer with syntax highlighting and search |710| `k8s-deploy` | Deployment dashboard with rollout status, scaling, rollback |711| `k8s-helm` | Helm release manager with upgrade/rollback actions |712| `k8s-cluster` | Cluster overview with node health and resource metrics |713| `k8s-cost` | Cost analyzer with waste detection and recommendations |714| `k8s-events` | Events timeline with type filtering and grouping |715| `k8s-network` | Network topology graph showing Services/Pods/Ingress |716717**Features:**718- 🎨 Dark/light theme support719- 📊 Real-time data visualization720- 🖱️ Interactive actions (scale, restart, delete)721- 🔗 Seamless integration with kubectl-mcp-server722723**More Info**: See [kubectl-mcp-app/README.md](./kubectl-mcp-app/README.md) for full documentation.724725## Enterprise: OAuth 2.1 Authentication726727Secure your MCP server with OAuth 2.1 authentication (RFC 9728).728729```bash730export MCP_AUTH_ENABLED=true731export MCP_AUTH_ISSUER=https://your-idp.example.com732export MCP_AUTH_AUDIENCE=kubectl-mcp-server733kubectl-mcp-server --transport http --port 8000734```735736**Supported Identity Providers**: Okta, Auth0, Keycloak, Microsoft Entra ID, Google OAuth, and any OIDC-compliant provider.737738**Use Case**: Multi-tenant environments, compliance requirements, audit logging.739740## Integrations & Ecosystem741742### Docker MCP Toolkit743744Works with [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/):745746```bash747docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest748docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/root/.kube:ro"749docker mcp server enable kubectl-mcp-server750docker mcp client connect claude751```752753### agentregistry754755Install from the centralized [agentregistry](https://aregistry.ai):756757```bash758# Install arctl CLI759curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/install.sh | bash760761# Install kubectl-mcp-server762arctl mcp install io.github.rohitg00/kubectl-mcp-server763```764765**Available via**: PyPI (`uvx`), npm (`npx`), OCI (`docker.io/rohitghumare64/kubectl-mcp-server`)766767### agentgateway768769Route to multiple MCP servers through [agentgateway](https://github.com/agentgateway/agentgateway):770771```bash772# Start with streamable-http773kubectl-mcp-server --transport streamable-http --port 8000774775# Configure gateway776cat > gateway.yaml <<EOF777binds:778- port: 3000779 listeners:780 - routes:781 - backends:782 - mcp:783 targets:784 - name: kubectl-mcp-server785 mcp:786 host: http://localhost:8000/mcp787EOF788789# Start gateway790agentgateway --config gateway.yaml791```792793Connect clients to `http://localhost:3000/mcp` for unified access to all 253 tools.794795## In-Cluster Deployment796797### Option 1: kMCP (Recommended)798799Deploy with [kMCP](https://github.com/kagent-dev/kmcp) - a control plane for MCP servers:800801```bash802# Install kMCP803curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash804kmcp install805806# Deploy kubectl-mcp-server (easiest)807kmcp deploy package --deployment-name kubectl-mcp-server \808 --manager npx --args kubectl-mcp-server809810# Or with Docker image811kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest812```813814See [kMCP quickstart](https://kagent.dev/docs/kmcp/quickstart) for details.815816### Option 2: Standard Kubernetes817818Deploy with kubectl/kustomize:819820```bash821# Using kustomize (recommended)822kubectl apply -k deploy/kubernetes/823824# Or individual manifests825kubectl apply -f deploy/kubernetes/namespace.yaml826kubectl apply -f deploy/kubernetes/rbac.yaml827kubectl apply -f deploy/kubernetes/deployment.yaml828kubectl apply -f deploy/kubernetes/service.yaml829830# Access via port-forward831kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000832```833834See [deploy/](deploy/) directory for all manifests and configuration options.835836### Option 3: kagent (AI Agent Framework)837838Integrate with [kagent](https://github.com/kagent-dev/kagent) - a CNCF Kubernetes-native AI agent framework:839840```bash841# Install kagent842brew install kagent843kagent install --profile demo844845# Register as ToolServer846kubectl apply -f deploy/kagent/toolserver-stdio.yaml847848# Open dashboard849kagent dashboard850```851852Your AI agents now have access to all 253 Kubernetes tools. See [kagent quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart).853854## Architecture855856```857┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐858│ AI Assistant │────▶│ MCP Server │────▶│ Kubernetes API │859│ (Claude/Cursor) │◀────│ (kubectl-mcp) │◀────│ (kubectl) │860└─────────────────┘ └──────────────────┘ └─────────────────┘861```862863The MCP server implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), translating natural language requests into kubectl operations.864865### Modular Structure866867```868kubectl_mcp_tool/869├── mcp_server.py # Main server (FastMCP, transports)870├── tools/ # 253 MCP tools organized by category871│ ├── pods.py # Pod management & diagnostics872│ ├── deployments.py # Deployments, StatefulSets, DaemonSets873│ ├── core.py # Namespaces, ConfigMaps, Secrets874│ ├── cluster.py # Context/cluster management875│ ├── networking.py # Services, Ingress, NetworkPolicies876│ ├── storage.py # PVCs, StorageClasses, PVs877│ ├── security.py # RBAC, ServiceAccounts, PodSecurity878│ ├── helm.py # Complete Helm v3 operations879│ ├── operations.py # kubectl apply/patch/describe/etc880│ ├── diagnostics.py # Metrics, namespace comparison881│ ├── cost.py # Resource optimization & cost analysis882│ ├── ui.py # MCP-UI interactive dashboards883│ ├── gitops.py # GitOps (Flux/ArgoCD)884│ ├── certs.py # Cert-Manager885│ ├── policy.py # Policy (Kyverno/Gatekeeper)886│ ├── backup.py # Backup (Velero)887│ ├── keda.py # KEDA autoscaling888│ ├── cilium.py # Cilium/Hubble network observability889│ ├── rollouts.py # Argo Rollouts/Flagger890│ ├── capi.py # Cluster API891│ ├── kubevirt.py # KubeVirt VMs892│ ├── kiali.py # Istio/Kiali service mesh893│ └── vind.py # vCluster (virtual clusters)894├── resources/ # 8 MCP Resources for data exposure895├── prompts/ # 8 MCP Prompts for workflows896└── cli/ # CLI interface897```898899## Agent Skills (25 Skills for AI Coding Agents)900901Extend your AI coding agent with Kubernetes expertise using our [Agent Skills](https://agenstskills.com) library. Skills provide specialized knowledge and workflows that agents can load on demand.902903### Quick Install904905```bash906# Copy all skills to Claude907cp -r kubernetes-skills/claude/* ~/.claude/skills/908909# Or install specific skills910cp -r kubernetes-skills/claude/k8s-helm ~/.claude/skills/911```912913### Available Skills (25)914915| Category | Skills |916|----------|--------|917| **Core Resources** | k8s-core, k8s-networking, k8s-storage |918| **Workloads** | k8s-deploy, k8s-operations, k8s-helm |919| **Observability** | k8s-diagnostics, k8s-troubleshoot, k8s-incident |920| **Security** | k8s-security, k8s-policy, k8s-certs |921| **GitOps** | k8s-gitops, k8s-rollouts |922| **Scaling** | k8s-autoscaling, k8s-cost, k8s-backup |923| **Multi-Cluster** | k8s-multicluster, k8s-capi, k8s-kubevirt, k8s-vind |924| **Networking** | k8s-service-mesh, k8s-cilium |925| **Tools** | k8s-browser, k8s-cli |926927### Convert to Other Agents928929Use [SkillKit](https://github.com/rohitg00/skillkit) to convert skills to your preferred AI agent format:930931```bash932npm install -g skillkit933934# Convert to Cursor format935skillkit translate kubernetes-skills/claude --to cursor --output .cursor/rules/936937# Convert to Codex format938skillkit translate kubernetes-skills/claude --to codex --output ./939```940941**Supported agents:** Claude, Cursor, Codex, Gemini CLI, GitHub Copilot, Goose, Windsurf, Roo, Amp, and more.942943See [kubernetes-skills/README.md](kubernetes-skills/README.md) for full documentation.944945## Multi-Cluster Support946947Seamlessly manage multiple Kubernetes clusters through natural language. **Every tool** supports an optional `context` parameter to target any cluster without switching contexts.948949### Context Parameter (v1.15.0)950951Most kubectl-backed tools accept an optional `context` parameter to target specific clusters.952Note: vCluster (vind) and kind tools run via their local CLIs and do not accept the `context` parameter.953954**Talk to your AI assistant:**955```956"List pods in the production cluster"957"Get deployments from staging context"958"Show logs from the api-pod in the dev cluster"959"Compare namespaces between production and staging clusters"960```961962**Direct tool calls with context:**963```bash964# Target a specific cluster context965kubectl-mcp-server call get_pods '{"namespace": "default", "context": "production"}'966967# Get deployments from staging968kubectl-mcp-server call get_deployments '{"namespace": "app", "context": "staging"}'969970# Install Helm chart to production cluster971kubectl-mcp-server call install_helm_chart '{"name": "redis", "chart": "bitnami/redis", "namespace": "cache", "context": "production"}'972973# Compare resources across clusters974kubectl-mcp-server call compare_namespaces '{"namespace1": "prod-ns", "namespace2": "staging-ns", "context": "production"}'975```976977### Context Management978979**Talk to your AI assistant:**980```981"List all available Kubernetes contexts"982"Switch to the production cluster"983"Show me details about the staging context"984"What's the current cluster I'm connected to?"985```986987**Or use the CLI directly:**988```bash989kubectl-mcp-server context # Show current context990kubectl-mcp-server context production # Switch context991kubectl-mcp-server call list_contexts_tool # List all contexts via MCP992```993994### How It Works995996- If `context` is omitted, the tool uses your current kubectl context997- If `context` is specified, the tool targets that cluster directly998- Response includes `"context": "production"` or `"context": "current"` for clarity999- Works with all kubeconfig setups and respects `KUBECONFIG` environment variable1000- No need to switch contexts for cross-cluster operations10011002## Development & Testing10031004### Setup Development Environment10051006```bash1007# Clone the repository1008git clone https://github.com/rohitg00/kubectl-mcp-server.git1009cd kubectl-mcp-server10101011# Create virtual environment1012python -m venv venv1013source venv/bin/activate # On Windows: venv\Scripts\activate10141015# Install development dependencies1016pip install -r requirements-dev.txt1017```10181019### Running Tests10201021```bash1022# Run all tests1023pytest tests/ -v10241025# Run specific test file1026pytest tests/test_tools.py -v10271028# Run with coverage1029pytest tests/ --cov=kubectl_mcp_tool --cov-report=html10301031# Run only unit tests1032pytest tests/ -v -m unit1033```10341035### Test Structure10361037```1038tests/1039├── __init__.py # Test package1040├── conftest.py # Shared fixtures and mocks1041├── test_tools.py # Unit tests for 253 MCP tools1042├── test_resources.py # Tests for 8 MCP Resources1043├── test_prompts.py # Tests for 8 MCP Prompts1044└── test_server.py # Server initialization tests1045```10461047**234 tests covering**: tool registration, resource exposure, prompt generation, server initialization, non-destructive mode, secret masking, error handling, transport methods, CLI commands, browser automation, and ecosystem tools.10481049### Code Quality10501051```bash1052# Format code1053black kubectl_mcp_tool tests10541055# Sort imports1056isort kubectl_mcp_tool tests10571058# Lint1059flake8 kubectl_mcp_tool tests10601061# Type checking1062mypy kubectl_mcp_tool1063```10641065## Contributing10661067We ❤️ contributions! Whether it's bug reports, feature requests, documentation improvements, or code contributions.10681069**Ways to contribute:**1070- 🐛 Report bugs via [GitHub Issues](https://github.com/rohitg00/kubectl-mcp-server/issues)1071- 💡 Suggest features or improvements1072- 📝 Improve documentation1073- 🔧 Submit pull requests1074- ⭐ Star the project if you find it useful!10751076**Development setup**: See [Development & Testing](#development--testing) section above.10771078**Before submitting a PR:**10791. Run tests: `pytest tests/ -v`10802. Format code: `black kubectl_mcp_tool tests`10813. Check linting: `flake8 kubectl_mcp_tool tests`10821083## Support & Community10841085- 📖 [Documentation](https://github.com/rohitg00/kubectl-mcp-server#readme)1086- 💬 [GitHub Discussions](https://github.com/rohitg00/kubectl-mcp-server/discussions)1087- 🐛 [Issue Tracker](https://github.com/rohitg00/kubectl-mcp-server/issues)1088- 🎯 [Feature Requests](https://github.com/rohitg00/kubectl-mcp-server/issues/new)1089- 🌟 [agentregistry Profile](https://aregistry.ai)10901091## License10921093MIT License - see [LICENSE](LICENSE) for details.10941095## Links & Resources10961097**Package Repositories:**1098- 🐍 [PyPI Package](https://pypi.org/project/kubectl-mcp-server/)1099- 📦 [npm Package](https://www.npmjs.com/package/kubectl-mcp-server)1100- 🐳 [Docker Hub](https://hub.docker.com/r/rohitghumare64/kubectl-mcp-server)11011102**Project:**1103- 🔧 [GitHub Repository](https://github.com/rohitg00/kubectl-mcp-server)1104- 🐛 [Issue Tracker](https://github.com/rohitg00/kubectl-mcp-server/issues)1105- 📋 [Changelog](https://github.com/rohitg00/kubectl-mcp-server/releases)11061107**Ecosystem:**1108- 📚 [Model Context Protocol](https://modelcontextprotocol.io)1109- ☸️ [Kubernetes Documentation](https://kubernetes.io/docs)11101111---11121113**Made with ❤️ for the Kubernetes and AI community**11141115If **kubectl-mcp-server** makes your DevOps life easier, give it a ⭐ on [GitHub](https://github.com/rohitg00/kubectl-mcp-server)!1116
Full transparency — inspect the skill content before installing.