io.github.your-ko/mcp-k8s-ro

Official

by your-ko · Go

Read-only Kubernetes MCP server: inspect resources, logs, events, and metrics. Secrets are masked.

Read-only Kubernetes inspection tool for resources, logs, events, and metrics.

Topics

k8sk8s-clustermcp-server

README.md8 KBView on GitHub

mcp-k8s-ro

A read-only MCP server that gives Claude access to Kubernetes clusters. Built in Go, it communicates over stdio using the MCP protocol.

Design

Read-only — only get, describe, logs, and top style operations. No create, update, or delete. If a mutating operation is needed, the server prints the equivalent kubectl command for you to run manually. Safe to use while on-call at night: Claude can never accidentally mutate your cluster, even under prompt fatigue.
Secret-safe — secret values are masked before being sent to the model, so your secrets cannot leak due to misconfiguration or prompt injection.
Token-efficient — responses include only relevant fields (name, status, restarts, etc.) rather than raw Kubernetes API objects, keeping context usage low.
Cluster-aware — every response includes the active context and cluster name, so Claude always knows which cluster it is talking to.
Context-pinned — the server locks to the active kubeconfig context at startup. Switching contexts in another terminal has no effect on the running server.
No extra infra — runs as a local binary or Docker container, connects to whatever kubeconfig context is active at startup.

Redacted fields

Object/Field	Reason
Secret.data	Secret leak prevention
Secret.stringData	Secret leak prevention
CertificateSigningRequest.spec.request	Large base64 PEM blob, no diagnostic value, saves tokens
Certificate (cert-manager) .spec.keystores	Cert chain PEM blobs, no diagnostic value, saves tokens
Certificate (cert-manager) status.conditions[].message	Cert chain PEM blobs, no diagnostic value, saves tokens
*.managedFields	No diagnostic value, saves tokens

Tools

Tool	Description
`k8s_list_resources`	List any resource type by name — pods, deployments, CRDs, etc. Accepts optional namespace filter. Returns name, status, readiness, restarts, node, IP, and more depending on resource kind.
`k8s_describe_resource`	Return the full YAML of a single resource. Secret data is masked.
`k8s_list_resource_types`	List all available resource types via the discovery API. Accepts optional API group filter.
`k8s_get_logs`	Fetch pod logs. Supports container selector, tail lines, and `--previous` for crashed containers.
`k8s_get_events`	List Kubernetes events for a namespace or the whole cluster, sorted by most recent.
`k8s_top_pods`	CPU and memory usage per pod, with per-container breakdown. Requires metrics-server.
`k8s_top_nodes`	CPU and memory usage per node, with percentage of allocatable capacity. Requires metrics-server.

Configuration

Environment variable	Default	Description
`KUBECONFIG`	`~/.kube/config`	Path to kubeconfig file

Usage with Claude

Binary

Build the binary and add it to your Claude Desktop or claude CLI configuration:

bash

make build
# binary is written to bin/mcp-k8s-ro

json

{
  "mcpServers": {
    "k8s": {
      "type" : "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

Or via the CLI:

bash

claude mcp add --transport stdio --scope user mcp-k8s-ro [path to binary]

Docker

Pull the image from GitHub Container Registry (pinning a specific version is recommended):

bash

docker pull ghcr.io/your-ko/mcp-k8s-ro:latest

Add it to your Claude Desktop or claude CLI configuration. The kubeconfig directory is mounted read-only into the container:

json

{
  "mcpServers": {
    "k8s": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/.kube:/home/nonroot/.kube:ro",
        "ghcr.io/your-ko/mcp-k8s-ro:latest"
      ]
    }
  }
}

If your kubeconfig is in a non-standard location, pass it via KUBECONFIG:

json

{
  "mcpServers": {
    "k8s": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "KUBECONFIG=/config/my-kubeconfig",
        "-v", "/path/to/my-kubeconfig:/config/my-kubeconfig:ro",
        "ghcr.io/your-ko/mcp-k8s-ro:latest"
      ]
    }
  }
}

Single-cluster design

The server intentionally operates on one kubeconfig context and provides no tool to switch clusters at runtime. The reasons are:

Prompt injection isolation — a malicious value in one cluster's resources (e.g. a pod annotation) cannot instruct Claude to pivot to a different cluster, including production.
Explicit audit boundary — every tool response includes the context and cluster name, so there is never ambiguity about which cluster was queried.

To point the server at a different cluster, stop the server, switch context, and restart:

bash

kubectl config use-context my-other-cluster
# then restart the MCP server / reload Claude Desktop

To work with multiple clusters simultaneously, register a separate server instance per cluster in your MCP config:

json

{
  "mcpServers": {
    "k8s-staging": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config" }
    },
    "k8s-prod": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config-prod" }
    }
  }
}

Claude will address each server by name and each instance only ever sees its own cluster.

MCP registry

This server is published on registry.modelcontextprotocol.io

Install

Configuration

Environment variables

KUBECONFIG

Path to the kubeconfig file. Defaults to ~/.kube/config.

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-k8s-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/your-ko/mcp-k8s-ro:1.1.0"
      ],
      "env": {
        "KUBECONFIG": "<YOUR_KUBECONFIG>"
      }
    }
  }
}