kops
A read-only kubectl helper that exposes Kubernetes cluster inspection to Claude Code via MCP, returning structured JSON instead of raw text tables.
Tools:
k8s_triage⭐ — One-shot cluster health diagnostic: fans out concurrentkubectlcalls to surface problem pods, recent warning events, unhealthy nodes, and stale deployments. Best starting point for "what's broken?" questions.k8s_inventory⭐ — One-shot comprehensive cluster snapshot replacing ~50 individualk8s_getcalls. Returns nodes, namespaces, workloads, services, ingresses, HPAs, PVCs, jobs, cronjobs, and optionally Istio CRDs and config resources. Supportsfull(expanded) oroverview(counts only) modes.k8s_get— List or fetch Kubernetes resources (pods, services, deployments, statefulsets, daemonsets, configmaps, secrets, nodes, ingresses, HPAs, PVCs, jobs, cronjobs, Istio CRDs) with summarized key fields; supports filtering by namespace, name, or label selector.k8s_describe— Detailedkubectl describeoutput for a single resource — events, conditions, container details, volume mounts, image pull state (truncated to ~30 KB).k8s_logs— Fetch pod logs with configurable tail lines (up to 1000), time-based filtering (since), specific container targeting, and previous crashed instance retrieval; capped at ~50 KB.k8s_events— List recent cluster events (most recent first), filterable by namespace, involved object kind/name, and recency window; useful for scheduling failures, image pull errors, OOMKills, etc.
Safety boundaries:
Strictly read-only — only
get,describe, andlogsverbs; no create, delete, apply, patch, scale, or exec.Input validation via regex for names, namespaces, and selectors;
shell=Falseto prevent injection.ConfigMap data and Secret values are never returned — metadata only.
30-second kubectl timeout; output size caps (30 KB describe, 50 KB logs).
Multi-cluster support via per-server
KUBECONFIGenvironment variables.
Provides read-only access to Istio resources (gateways, virtual services, destination rules) within a Kubernetes cluster for diagnostics and monitoring.
kops
Read-only kubectl helper exposed to Claude Code via MCP. Six tools, all strictly read-only — verbs (get, describe, logs) are hardcoded; user input only fills argument values, never the verb itself.

Tool | What it does |
| List/fetch resources, returns summarized key fields per kind |
|
|
| Pod logs with |
| Recent events filtered by namespace / kind / name |
| ⭐ One-shot cluster health scan — start here for diagnostics |
| ⭐ One-shot comprehensive snapshot — start here for documentation / audits |
Why
kubectl over Bash gives Claude text tables that need re-parsing every turn. Wrapping it as MCP returns structured JSON Claude can reason over directly — fewer tokens, fewer parse errors, and built-in safety boundaries (read-only verbs, name validation, output size caps).
Two aggregator tools (k8s_triage, k8s_inventory) compress common multi-step queries into single round-trips:
k8s_triage— "what's broken?" → 4 concurrent kubectl calls, returns problem pods + warning events + unhealthy nodes + stale deploymentsk8s_inventory— "show me everything" → 14+ concurrent kubectl calls, returns cluster-wide snapshot grouped by namespace. Replaces ~50 individualk8s_getcalls (~6× faster end-to-end for cluster docs).
Related MCP server: Kubernetes Tools MCP Server
Install
Requires uv and kubectl in your PATH.
git clone https://github.com/kaka-milan-22/kops.git
cd kops
uv syncThe commands below use
/path/to/kopsfor the absolute path of this clone — replace it with your actual path (e.g. the output ofpwdrun from inside the cloned directory).uv --directoryneeds an absolute path.
Smoke test (no cluster needed)
MCP requires a handshake (initialize → notifications/initialized) before any business request, so a bare tools/list over stdin is rejected with Received request before initialization was complete. Feed all three messages in order:
{
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
} | uv run kopsExpect: an initialize response, then a tools/list response listing the 6 tools with input schemas. (The notification has no id and produces no reply.)
Visual debug with MCP Inspector
For interactive debugging, skip the raw stdio dance and use the official tools — they handle the handshake for you:
# Option A: MCP Inspector (browser UI)
npx @modelcontextprotocol/inspector uv --directory /path/to/kops run kops
# Option B: mcp dev (bundled with the mcp[cli] extra already in deps)
uv run mcp dev src/kops/server.pyOpen the URL each prints, click a tool, exercise its parameters.
Register with Claude Code
claude mcp add -s user kops -- uv --directory /path/to/kops run kopsOr manually in ~/.claude.json under mcpServers:
{
"mcpServers": {
"kops": {
"command": "uv",
"args": ["--directory", "/path/to/kops", "run", "kops"]
}
}
}Reload Claude Code (or open a new session). Tools surface as mcp__kops__k8s_get, mcp__kops__k8s_triage, mcp__kops__k8s_inventory, etc.
Multi-cluster (kubeconfig isolation)
To talk to a foreign cluster without polluting ~/.kube/config, register a separate server entry with its own KUBECONFIG:
claude mcp add -s user -e KUBECONFIG=/path/to/qa-cluster.yaml \
kops-qa -- uv --directory /path/to/kops run kopsTools then surface as mcp__kops_qa__k8s_triage etc, fully isolated.
End-to-end smoke (with a kind cluster)
kind create cluster --name kops-test
kubectl run broken --image=nonexistent:fake --restart=Never
sleep 30Then in Claude Code, ask: "this cluster has problems, what's wrong?"
Expected: Claude calls mcp__kops__k8s_triage first, sees the broken pod in ImagePullBackOff, then k8s_describe for root cause.
For a documentation example, ask: "give me a full report of this cluster".
Expected: Claude calls mcp__kops__k8s_inventory once and assembles a structured markdown report covering nodes, namespaces, workloads, services, exposure surface, and configuration counts.
What k8s_get returns per kind
_summarize_resource extracts only the fields most useful for diagnostics and documentation. Avoids dumping full spec to keep token usage sane.
Kind | Summarized fields |
Pod |
|
Service |
|
Deployment |
|
StatefulSet / DaemonSet / ReplicaSet |
|
Node |
|
Ingress |
|
Namespace / generic |
|
Where resources is the sum across all main containers of requests and limits (init containers excluded — they don't run concurrently with steady state, so don't add to scheduling footprint). CPU normalized to millicores, memory normalized to binary units (Ki/Mi/Gi). Init containers still appear in images[] with an init: True flag.
What k8s_inventory returns
{
"summary": {
"scope": "cluster-wide" | "namespace=<name>",
"namespaces": int, "nodes": int, "pods_total": int,
"by_kind_counts": {"deployments": N, "services": N, ...},
"istio_present": bool,
"include_istio": bool,
},
"nodes": [<summarized node>, ...], # cluster-scoped only
"namespaces": [
{
"name": "...", "age": "...", "labels": {...},
"pods": int, # count only (full pod list not included)
"deployments": [<summarized>, ...],
"statefulsets": [...], "daemonsets": [...],
"services": [...], "ingresses": [...], "hpa": [...],
"pvcs": [...], "configmaps": [...], "secrets": [...],
"jobs": [...], "cronjobs": [...],
"istio_gateways": [...], "istio_virtualservices": [...], "istio_destinationrules": [...],
},
...
]
}ConfigMap data and Secret values are never returned — only metadata (names, key lists, age). This is a hard safety boundary; if you need actual config content, go through Bash + kubectl under explicit permission.
Pods are not included as a list (potentially huge). Use k8s_triage for pod health, k8s_get pod for specific pods.
Safety
Mutation defense: verb is hardcoded inside each tool function. User input only fills argument values, never the verb. There is no path to
delete/apply/patch/scale/execfrom any input.Injection defense:
subprocess.run([...], shell=False)everywhere. Names/namespaces/containers validated against^[a-zA-Z0-9._-]{1,253}$. Selectors validated against a K8s label-selector character set.Resource limits:
kubectlinvoked with 30s timeout. Logtailclamped to 1000 lines. Output size capped (30KB describe, 50KB logs).Context isolation: default uses
kubectl config current-context. The optionalcontextargument can override but cannot inject aKUBECONFIGpath. For full isolation across clusters, register a separate MCP server entry with its ownKUBECONFIGenv var.
Extending
Add another tool by writing a new @mcp.tool() function in src/kops/server.py:
Hardcode the verb.
Validate inputs with the existing helpers (
_validate_kind,_validate_name,_validate_selector,_validate_since).Call kubectl via
_run_kubectl([...]).Reuse
_summarize_resourcefor output shaping if your tool returns resources.Type hints on the function signature become the JSON-RPC input schema automatically (FastMCP handles this).
For aggregator tools (triage / inventory style), follow the pattern: build a list of kubectl get -A -o json arg vectors, fan out via ThreadPoolExecutor(max_workers=8), post-process and group locally. CRD detection is graceful — wrap the per-kind kubectl call in a try/except RuntimeError and skip absent kinds silently.
Available Tools
6 toolsk8s_describeA
Describe a single K8s resource (text output from kubectl describe).
Read-only: runs kubectl describe only — never mutates the cluster,
idempotent. Requires read access to the resource; raises on kubectl failure
(e.g. NotFound, Forbidden). Returns human-readable TEXT (not JSON), truncated
to ~30 KB. Use when k8s_get isn't enough — describe shows events, conditions,
container details, volume mounts, image pull state, etc.
Args: kind: Resource kind. name: Resource name (required). namespace: Target namespace. context: kubeconfig context.
Inputs: kind (required), name (required), context, namespace. Returns: result
k8s_eventsA
List recent K8s events, most recent first.
Read-only: lists events only — never mutates the cluster, idempotent. Requires read access to events; raises on kubectl failure. Use this to surface scheduling failures, image pull problems, OOMKilled, network issues, etc. Filter by namespace and/or involved object.
Args:
namespace: Target namespace; omit for cluster-wide.
kind: Filter by involvedObject.kind (e.g. "Pod").
name: Filter by involvedObject.name (use with kind).
since: Look-back window (default "30m"). Format: "Ns", "Nm", "Nh", "Nd".
context: kubeconfig context.
Inputs: kind, name, since, context, +1 more. Returns: result
k8s_getA
List or fetch K8s resources, returning summarized key fields per resource.
Read-only: runs kubectl get -o json only — never creates, mutates, or
deletes anything, and is safe to call repeatedly (idempotent). Requires a
kubeconfig with read/list access to the target kind/namespace; raises on
kubectl failure (e.g. NotFound, Forbidden, unreachable cluster). Output is
summarized (not raw spec) to keep tokens low; Secret/ConfigMap values are
never included. For deeper detail (events, conditions, container info), use
k8s_describe.
Args: kind: Resource kind. Common: pod, svc, deploy, sts, ds, cm, secret, ns, node, ingress, gateway, virtualservice, destinationrule, hpa, pvc. namespace: Target namespace; omit to scan all namespaces. name: Specific resource name; omit to list multiple. selector: K8s label selector, e.g. "app=foo,env=prod". context: kubeconfig context to use; defaults to current context.
Inputs: kind (required), name, context, selector, +1 more. Returns: result
k8s_inventoryA
⭐ One-shot comprehensive cluster snapshot. Use for documentation, audits, or any task that needs broad visibility — replaces ~50 individual k8s_get calls.
Read-only: fans out many kubectl get -o json calls only — never mutates the
cluster, idempotent. Requires broad read access (or read on the given
namespace); kinds that are Forbidden/absent are skipped silently rather than
failing the whole call. Pods are excluded from the payload (counts only).
Modes:
"full" (default): expand each namespaced item to its summarized form (deployment images, service ports, etc.). Use for documentation or audits.
"overview": skip per-item expansion. Each namespace entry carries only a
by_kind_countsmap. ~10-20× smaller payload. Use to scan cluster shape before drilling in with namespace-scoped follow-up calls.
By default, ConfigMap and Secret lists are EXCLUDED — they are typically the largest noise-to-signal source in cluster-wide inventories. Set include_config_resources=True to include them in by_kind_counts and the per-namespace breakdown. ConfigMap data and Secret values are NEVER returned — only metadata.
Pods are NOT included in the snapshot (potentially huge); only per-namespace pod counts are surfaced. Use k8s_triage for pod health, k8s_get pod for specifics.
Istio CRDs (Gateway / VirtualService / DestinationRule) are auto-included when present; absent CRDs are silently skipped. Set include_istio=False to skip.
Args: namespace: Limit scope to a single namespace; omit for cluster-wide. mode: "full" (default, expand items) or "overview" (counts only). include_config_resources: Include ConfigMaps and Secrets (default False). include_istio: Auto-detect and include Istio CRDs (default True). context: kubeconfig context.
Inputs: mode, context, namespace, include_istio, +1 more.
k8s_logsA
Fetch logs from a pod.
Read-only: runs kubectl logs only — never mutates the cluster, idempotent.
Requires read access to pod logs; raises on kubectl failure (e.g. pod
NotFound, container not yet started, Forbidden). Output is truncated to
~50 KB.
Args: pod: Pod name (required). namespace: Target namespace. container: Container name in multi-container pods. tail: Lines from the tail (default 100, hard max 1000). since: Look-back window like "5m", "1h"; only logs newer than this. previous: If True, fetch the previous container instance's logs (post-crash). context: kubeconfig context.
Inputs: pod (required), tail, since, context, +3 more. Returns: result
k8s_triageA
⭐ Start here for cluster diagnostics. Single call returns: problem pods, recent warning events, unhealthy nodes, and stale deployments.
Read-only: fans out several kubectl get calls only — never mutates the
cluster, idempotent. Requires read access cluster-wide (or to the given
namespace); individual sub-queries that are Forbidden/absent are skipped
rather than aborting. Use this as the FIRST tool for broad questions like
"what's wrong with this cluster", "anything broken", or "give me a health
summary", then dig deeper with k8s_describe / k8s_logs / k8s_events.
Args: namespace: Limit scope to a single namespace; omit for cluster-wide. since: Event recency window (default "1h"). Format: "Ns", "Nm", "Nh", "Nd". context: kubeconfig context.
Inputs: since, context, namespace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool serves a distinct read-only purpose: describe details, list events, get summarized resources, inventory cluster snapshot, fetch logs, and triage diagnostics. No overlap.
All tools follow the consistent pattern 'k8s_<verb or noun>' using lowercase and underscores. While some names are nouns (events, inventory, triage), they clearly describe the action and maintain alignment.
With 6 tools, the set is well-scoped for a Kubernetes read-only diagnostic server, covering the essential operations without being over- or under-inclusive.
The tool set comprehensively addresses common diagnostic tasks: listing, describing, logs, events, inventory, and triage. No obvious gaps for read-only operations.
Maintenance
Related MCP Connectors
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
Read-only Google Search Console MCP server for AI assistants.
Read-only Google Analytics 4 MCP server for AI assistants.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides read-only access to Kubernetes clusters for AI assistants.25MIT
- AlicenseAqualityAmaintenanceProvides a set of read-only Kubernetes functions via an MCP server, enabling interaction with Kubernetes clusters through agents or coding assistants like GitHub Copilot.21102 PyPI3Apache 2.0
- AlicenseAqualityBmaintenanceRead-only MCP server for safe Kubernetes inspection, diagnosis, and debugging. Supports Kubernetes core, Helm, Argo Workflows, and Argo CD.2133 npm5MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for inspecting Kubernetes clusters, allowing LLMs to list resources, describe pods, and read logs without mutation.5MIT