mcp-k8s-ro

A read-only MCP server that gives Claude access to Kubernetes clusters. Built in Go, 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

Tools

Configuration

Usage with Claude

Binary

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

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

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

Or via the CLI:

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):

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:

{
  "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:

{
  "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:

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:

{
  "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 .claude.jsonserver by name and each instance only ever sees its own cluster.

MCP registry

This server is published on registry.modelcontextprotocol.io