Kubernetes MCP Usage

Kubernetes MCP Usage Guide

When to Use

Use this skill when the user wants to operate Kubernetes through kubernetes-mcp:

• connect MCP client to this server (stdio, sse, streamable);
• discover resources, inspect cluster state, check logs/events/metrics;
• troubleshoot failed tool calls and parameter mismatch.

Connection Checklist

1. Confirm server is reachable:
   • stdio: binary command works with local kubeconfig.
   • streamable: endpoint is POST /mcp.
2. Confirm Kubernetes auth is valid:
   • explicit --kubeconfig or in-cluster service account.
3. Prefer smallest-scope query first:
   • namespace + kind filters before wide cluster scans.

Recommended Tool Flow

1. Health and inventory:
   • GET_CLUSTER_INFO
   • LIST_NAMESPACES
2. Resource location:
   • SEARCH_RESOURCES (supports name=..., label=..., annotation=..., wildcard *)
   • LIST_K8S_RESOURCES
3. Deep inspection:
   • GET_K8S_RESOURCE / DESCRIBE_K8S_RESOURCE
   • GET_EVENTS
4. Runtime diagnosis:
   • GET_POD_LOGS
   • GET_POD_METRICS, GET_NODE_METRICS, GET_TOP_CONSUMERS

Practical Query Patterns

• Find all pods in namespace:
  • SEARCH_RESOURCES {"kinds":"Pod","namespaces":"mcp-system","query":"name=*"}
• Find by label wildcard:
  • SEARCH_RESOURCES {"query":"label=app:nginx-*","namespaces":"default"}
• Find by annotation:
  • SEARCH_RESOURCES {"query":"annotation=team:platform","namespaces":"default"}
• List known kind explicitly:
  • LIST_K8S_RESOURCES {"kind":"Pod","apiVersion":"v1","namespace":"default"}
• List namespace resources by discovery:
  • LIST_K8S_RESOURCES {"namespace":"default"}

Error Handling Guidance

• If listing fails with missing apiVersion:
  • provide both kind and apiVersion, or omit kind for discovery listing.
• If search returns empty unexpectedly:
  • check kinds value (Pod/pods both accepted),
  • verify namespace scope,
  • test with query:"name=*" first.
• If metrics tools fail:
  • confirm metrics-server is installed and accessible.

Safety

• Avoid destructive actions (DELETE, large apply) unless user explicitly requests.
• For changes, prefer VALIDATE_MANIFEST and DIFF_MANIFEST before APPLY_MANIFEST.

Source: HSn0918/kubernetes-mcp — distributed by TomeVault.