Kubectl MCP Tool

<p align="center"> <img src="logos/kubectl-mcp-server-icon.svg" alt="kubectl-mcp-server logo" width="80" height="80"> <br> <strong style="font-size: 24px;">kubectl-mcp-server</strong> </p> <p align="center"> <b>Control your entire Kubernetes infrastructure through natural language conversations with AI.</b><br> 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.<br> <b>Part of CNCF Landscape, Next to Terraform</b> </p> <img width="2473" height="1332" alt="Screenshot 2026-04-08 at 23 36 21" src="https://github.com/user-attachments/assets/616b4e65-37bc-474e-8124-68e64c6d7c95" /> <p align="center"> <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> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python"></a> <a href="https://kubernetes.io/"><img src="https://img.shields.io/badge/kubernetes-%23326ce5.svg?style=flat&logo=kubernetes&logoColor=white" alt="Kubernetes"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP"></a> </p> <p align="center"> <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> <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> <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> <a href="https://github.com/rohitg00/kubectl-mcp-server"><img src="https://img.shields.io/badge/tests-234%20passed-success" <a href="https://deepwiki.com/rohitg00/kubectl-mcp-server"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a> <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> </p> --- ## Installation ### Quick Start with npx (Recommended - Zero Install) ```bash # 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) ```bash # 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?](#what-can-you-do) - [Why kubectl-mcp-server?](#why-kubectl-mcp-server) - [Live Demos](#live-demos) - [Installation](#installation) - [Quick Start with npx](#quick-start-with-npx-recommended---zero-install) - [Install with pip](#or-install-with-pip-python) - [Docker](#docker) - [Getting Started](#getting-started) - [Quick Setup with Your AI Assistant](#quick-setup-with-your-ai-assistant) - [All Supported AI Assistants](#all-supported-ai-assistants) - [Complete Feature Set](#complete-feature-set) - [Using the CLI](#using-the-cli) - [Advanced Configuration](#advanced-configuration) - [Optional Features](#optional-interactive-dashboards-6-ui-tools) - [Interactive Dashboards](#optional-interactive-dashboards-6-ui-tools) - [Browser Automation](#optional-browser-automation-26-tools) - [Enterprise](#enterprise-oauth-21-authentication) - [Integrations & Ecosystem](#integrations--ecosystem) - [In-Cluster Deployment](#in-cluster-deployment) - [Multi-Cluster Support](#multi-cluster-support) - [Architecture](#architecture) - [Agent Skills](#agent-skills-24-skills-for-ai-coding-agents) - [Development & Testing](#development--testing) - [Contributing](#contributing) - [Support & Community](#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) ```bash # 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) ```bash # Standard installation pip install kubectl-mcp-server # With interactive UI dashboards (recommended) pip install kubectl-mcp-server[ui] ``` ### Install from GitHub Release ```bash # 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 ```bash # 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: ```bash # 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`: ```json { "mcpServers": { "kubernetes": { "command": "npx", "args": ["-y", "kubectl-mcp-server"] } } } ``` ### Cursor AI Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "kubernetes": { "command": "npx", "args": ["-y", "kubectl-mcp-server"] } } } ``` ### Windsurf Add to `~/.config/windsurf/mcp.json`: ```json { "mcpServers": { "kubernetes": { "command": "npx", "args": ["-y", "kubectl-mcp-server"] } } } ``` ### Using Python Instead of npx ```json { "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](#mcp-client-compatibility) —> see [full configuration guide](#all-supported-ai-assistants) 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`: ```json { "mcpServers": { "kubernetes": { "command": "npx", "args": ["-y", "kubectl-mcp-server"] } } } ``` ### GitHub Copilot (VS Code) Add to VS Code `settings.json`: ```json { "mcp": { "servers": { "kubernetes": { "command": "npx", "args": ["-y", "kubectl-mcp-server"] } } } } ``` ### Goose Add to `~/.config/goose/config.yaml`: ```yaml extensions: kubernetes: command: npx args: - -y - kubectl-mcp-server ``` ### Gemini CLI Add to `~/.gemini/settings.json`: ```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`: ```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: ```bash # 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: ```bash # 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_JWKS_URI` | JWKS endpoint URL | Auto-derived | | `MCP_AUTH_AUDIENCE` | Expected token audience | `kubectl-mcp-server` | | `MCP_AUTH_REQUIRED_SCOPES` | Required OAuth scopes | `mcp:tools` | **Browser Automation (Optional):** | Variable | Description | Default | |----------|-------------|---------| | `MCP_BROWSER_ENABLED` | Enable browser automation tools | `false` | | `MCP_BROWSER_PROVIDER` | Cloud provider (browserbase/browseruse) | None | | `MCP_BROWSER_PROFILE` | Persistent profile path | None | | `MCP_BROWSER_CDP_URL` | Remote CDP WebSocket URL | None | | `MCP_BROWSER_PROXY` | Proxy server URL | None | ## Optional: Interactive Dashboards (6 UI Tools) Get beautiful HTML dashboards for visual cluster management. **Installation:** ```bash # Install with UI support pip install kubectl-mcp-server[ui] ``` **6 Dashboard Tools:** - 📊 `show_pods_dashboard_ui` - Real-time pod status table - 📝 `show_pod_logs_ui` - Interactive log viewer with search - 🎯 `show_cluster_overview_ui` - Complete cluster dashboard - ⚡ `show_events_timeline_ui` - Events timeline with filtering - 📄 `show_resource_yaml_ui` - YAML viewer with syntax highlighting - 📸 `render_k8s_dashboard_screenshot` - Export dashboards as PNG **Features:** - 🎨 Dark theme optimized for terminals (Catppuccin) - 🔄 Graceful fallback to JSON for incompatible clients - 🖼️ Screenshot rendering for universal compatibility - 🚀 Zero external dependencies **Works With**: Goose, LibreChat, Nanobot (full HTML UI) | Claude Desktop, Cursor, others (JSON + screenshots) ## Optional: Browser Automation (26 Tools) Automate web-based Kubernetes operations with [agent-browser](https://github.com/vercel-labs/agent-browser) integration. **Quick Setup:** ```bash # Install agent-browser npm install -g agent-browser agent-browser install # Enable browser tools export MCP_BROWSER_ENABLED=true kubectl-mcp-server ``` **What You Can Do:** - 🌐 Test deployed apps via Ingress URLs - 📸 Screenshot Grafana, ArgoCD, or any K8s dashboard - ☁️ Automate cloud console operations (EKS, GKE, AKS) - 🏥 Health check web applications - 📄 Export monitoring dashboards as PDF - 🔐 Test authentication flows with persistent sessions **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) **Advanced Features**: - Cloud providers: Browserbase, Browser Use - Persistent browser profiles - Remote CDP connections - Session management ## Optional: kubectl-mcp-app (8 Interactive UI Dashboards) A standalone npm package that provides beautiful, interactive UI dashboards for Kubernetes management using the MCP ext-apps SDK. **Installation:** ```bash # Via npm npm install -g kubectl-mcp-app # Or via npx (no install) npx kubectl-mcp-app ``` **Claude Desktop Configuration:** ```json { "mcpServers": { "kubectl-app": { "command": "npx", "args": ["kubectl-mcp-app"] } } } ``` **8 Interactive UI Tools:** | Tool | Description | | ---- | ----------- | | `k8s-pods` | Interactive pod viewer with filtering, sorting, status indicators | | `k8s-logs` | Real-time log viewer with syntax highlighting and search | | `k8s-deploy` | Deployment dashboard with rollout status, scaling, rollback | | `k8s-helm` | Helm release manager with upgrade/rollback actions | | `k8s-cluster` | Cluster overview with node health and resource metrics | | `k8s-cost` | Cost analyzer with waste detection and recommendations | | `k8s-events` | Events timeline with type filtering and grouping | | `k8s-network` | Network topology graph showing Services/Pods/Ingress | **Features:** - 🎨 Dark/light theme support - 📊 Real-time data visualization - 🖱️ Interactive actions (scale, restart, delete) - 🔗 Seamless integration with kubectl-mcp-server **More Info**: See [kubectl-mcp-app/README.md](./kubectl-mcp-app/README.md) for full documentation. ## Enterprise: OAuth 2.1 Authentication Secure your MCP server with OAuth 2.1 authentication (RFC 9728). ```bash export MCP_AUTH_ENABLED=true export MCP_AUTH_ISSUER=https://your-idp.example.com export MCP_AUTH_AUDIENCE=kubectl-mcp-server kubectl-mcp-server --transport http --port 8000 ``` **Supported Identity Providers**: Okta, Auth0, Keycloak, Microsoft Entra ID, Google OAuth, and any OIDC-compliant provider. **Use Case**: Multi-tenant environments, compliance requirements, audit logging. ## Integrations & Ecosystem ### Docker MCP Toolkit Works with [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/): ```bash docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/root/.kube:ro" docker mcp server enable kubectl-mcp-server docker mcp client connect claude ``` ### agentregistry Install from the centralized [agentregistry](https://aregistry.ai): ```bash # Install arctl CLI curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/install.sh | bash # Install kubectl-mcp-server arctl mcp install io.github.rohitg00/kubectl-mcp-server ``` **Available via**: PyPI (`uvx`), npm (`npx`), OCI (`docker.io/rohitghumare64/kubectl-mcp-server`) ### agentgateway Route to multiple MCP servers through [agentgateway](https://github.com/agentgateway/agentgateway): ```bash # Start with streamable-http kubectl-mcp-server --transport streamable-http --port 8000 # Configure gateway cat > gateway.yaml <<EOF binds: - port: 3000 listeners: - routes: - backends: - mcp: targets: - name: kubectl-mcp-server mcp: host: http://localhost:8000/mcp EOF # Start gateway agentgateway --config gateway.yaml ``` Connect clients to `http://localhost:3000/mcp` for unified access to all 253 tools. ## In-Cluster Deployment ### Option 1: kMCP (Recommended) Deploy with [kMCP](https://github.com/kagent-dev/kmcp) - a control plane for MCP servers: ```bash # Install kMCP curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash kmcp install # Deploy kubectl-mcp-server (easiest) kmcp deploy package --deployment-name kubectl-mcp-server \ --manager npx --args kubectl-mcp-server # Or with Docker image kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest ``` See [kMCP quickstart](https://kagent.dev/docs/kmcp/quickstart) for details. ### Option 2: Standard Kubernetes Deploy with kubectl/kustomize: ```bash # Using kustomize (recommended) kubectl apply -k deploy/kubernetes/ # Or individual manifests kube