kubectl-mcp-server MCP — Use Cases, Install & Live Demo

Why use it

Key features

253 tools covering pods, deployments, services, RBAC, networking
Ecosystem coverage: Helm, Flux, ArgoCD, Cert-Manager, Velero, KEDA, Istio
Cost optimization: detects over-provisioned resources, saves recommendations
OAuth 2.1 mode for secured multi-tenant SRE platforms

Live Demo

What it looks like in practice

kubectl.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kubectl": {
      "command": "uvx",
      "args": [
        "kubectl-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "kubectl": {
      "command": "uvx",
      "args": [
        "kubectl-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "kubectl": {
      "command": "uvx",
      "args": [
        "kubectl-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "kubectl": {
      "command": "uvx",
      "args": [
        "kubectl-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "kubectl",
      "command": "uvx",
      "args": [
        "kubectl-mcp-server"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "kubectl": {
      "command": {
        "path": "uvx",
        "args": [
          "kubectl-mcp-server"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add kubectl -- uvx kubectl-mcp-server

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use kubectl-mcp-server

Triage a CrashLoopBackOff pod in 60 seconds

👤 On-call SREs ⏱ ~10 min intermediate

When to use: Alerts fire; you want to see logs, events, and resource usage before digging in kubectl manually.

Prerequisites

kubectl configured with cluster access — kubectl config get-contexts should list your cluster

Flow

Identify crashing pods

List pods in namespace X with restart count > 5. Show pod name, container, and last exit reason.✓ Copied

→ Narrowed list
Pull logs + events

For pod Y, get last 100 lines of logs and the related events. Highlight any error keywords.✓ Copied

→ Likely root cause
Check resource pressure

Show CPU/memory limits vs actual for the pod. OOM killed?✓ Copied

→ Resource verdict

Outcome: A focused hypothesis in a minute, not ten kubectl commands.

Pitfalls

Wrong cluster context — Always specify --context in your prompt; the default can bite you across prod/staging

Combine with: prometheus

Find over-provisioned workloads to trim your cluster bill

👤 FinOps, platform engineers ⏱ ~40 min advanced

When to use: Quarterly cost reviews — you want data-driven scale-down candidates.

Flow

Run the cost analysis

Use the cost-optimization tools to find deployments where request/limit is 3x actual over the last 30 days.✓ Copied

→ Ranked list of over-provisioned workloads
Estimate savings

For the top 10, estimate $ saved per month if right-sized. Group by team.✓ Copied

→ Per-team savings table
File PRs with suggested manifests

Generate updated manifests for the top 5 and file PRs in the appropriate repos.✓ Copied

→ PRs opened with proposed diffs

Outcome: Visible cost wins backed by metrics, with follow-through via PRs.

Combine with: github · prometheus

Upgrade a Helm release safely with Claude

👤 Platform engineers ⏱ ~20 min advanced

When to use: Routine Helm upgrades shouldn't require 20 minutes of ceremony.

Flow

Diff new vs current

For release X, show diff between values.yaml and the new chart version.✓ Copied

→ Value/template diff
Dry-run

Run helm upgrade --dry-run with the new chart. Report any rendered template issues.✓ Copied

→ Clean dry-run or actionable errors
Upgrade with rollback ready

Apply the upgrade. Immediately after, verify rollout status and keep the previous revision ready for rollback.✓ Copied

→ Deployed successfully with rollback instructions

Outcome: Lower-risk Helm ops with a rollback path explicit from the start.

Audit RBAC for overly-permissive roles

👤 Security engineers ⏱ ~30 min advanced

When to use: Pre-certification or after noticing a suspicious role.

Flow

List wildcard roles

Find ClusterRoles or Roles with '*' in resources or verbs. Group by namespace.✓ Copied

→ Wildcard RBAC list
Map to subjects

For each, who's bound to it? List ServiceAccounts/Users/Groups.✓ Copied

→ Subject-role matrix
Suggest minimal replacements

For the top 5 riskiest, suggest minimum required verbs based on actual usage (audit logs).✓ Copied

→ Concrete tightening proposals

Outcome: Tightened RBAC with defensible diffs.

Combinations

Pair with other MCPs for X10 leverage

kubectl + prometheus

Cross-reference pod state with Prometheus metrics

For pod X, show kubectl describe output alongside its last 24h CPU/memory from Prometheus.✓ Copied

kubectl + github

RBAC audit → PRs that tighten YAML manifests

For each finding in the RBAC audit, open a PR against the infra repo with a minimized Role YAML.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
kubectl_get	resource, namespace?, label_selector?	List anything	1 API call
kubectl_describe	resource, name, namespace?	Deep detail on a single object	1 API call
pod_logs	pod, container?, tail?, namespace?	Debug	1 API call
pod_events	pod, namespace?	Why did this happen?	1 API call
helm_list	namespace?	Overview Helm releases	helm cmd
helm_upgrade	release, chart, values?, dry_run?	Deploy	helm cmd
cost_optimize	namespace?, period?	FinOps sweeps	metrics API
rbac_audit		Security review	several API calls

Cost & Limits

What this costs to run

API quota: Limited by your cluster's API server capacity
Tokens per call: kubectl output can be large — describe/get-wide especially
Monetary: Free MCP; cluster costs are yours
Tip: Prefer label_selector and field selectors over listing everything; avoid --output=wide in prompts

Security

Permissions, secrets, blast radius

Minimum scopes: cluster read-only unless you need writes

Credential storage: Standard KUBECONFIG; MCP doesn't store creds separately

Data egress: Your K8s API server only

Never grant: cluster-admin to the MCP context unless absolutely necessary

Troubleshooting

Common errors and fixes

Unauthorized / forbidden

KUBECONFIG context lacks permissions. Check kubectl auth can-i for the specific verb/resource

Verify: kubectl auth can-i get pods --namespace X

Context confusion between clusters

Always set or pass --context explicitly; a wrong context on prod is a bad day

Verify: kubectl config current-context

Helm upgrade fails mid-way

Use helm rollback <release> <prev-rev>; always capture prev revision before upgrading

Alternatives

kubectl-mcp-server vs others

Alternative	When to use it instead	Tradeoff
k8s-mcp-server (official-ish, smaller)	You only need basic kubectl and worry about the 253-tool surface noise	Fewer ecosystem tools (no Helm/Flux)
Direct kubectl in a shell	You're deep in a terminal session already	No agent loop

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills