Skip to main content
Glama
k8s-readonly-mcp

k8s-readonly-mcp

by ziyuyu23

k8s-readonly-mcp

A read-only Model Context Protocol (MCP) server that lets an LLM inspect a Kubernetes cluster — list pods, read logs, describe resources — but never mutate it.

Why I built it

I spend a lot of time embedded in customer Kubernetes environments. The most common thing I want from an LLM is "help me understand what's happening in this cluster" — without ever giving it the ability to change anything. So I built the safety in structurally rather than trusting the model to behave.

Every tool call routes through a single function that checks the kubectl verb against an allow-list of read-only verbs (get, describe, logs, top, …). There is no code path that can apply, delete, scale, or exec. If the model asks for a mutation, the server refuses. This is the same least-privilege, human-in-the-loop instinct that any production agent needs.

Related MCP server: kubernetes-mcp

What it does

Tool

Description

list_namespaces

List all namespaces

list_pods

List pods in a namespace (or all namespaces)

describe_pod

Full status, events, and config for one pod

get_pod_logs

Last N lines of a pod's logs

list_deployments

Deployments and their ready/up-to-date status

Quick start

Prerequisite: kubectl must be installed and on your PATH.

# 1. Install (using uv — https://docs.astral.sh/uv/)
uv sync

# 2. Make sure kubectl points at a cluster.
#    A local cluster is perfect for trying this safely:
#    kind create cluster   (or: minikube start)
kubectl get nodes

# 3. Run the server
uv run k8s-readonly-mcp

Connect it to Claude Desktop

Add this to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "k8s-readonly": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/k8s-readonly-mcp", "run", "k8s-readonly-mcp"]
    }
  }
}

Then ask Claude things like "What pods are failing in the default namespace, and why?" — it will call list_pods and describe_pod, reason over the output, and explain — but it physically cannot change your cluster.

Design decisions

  • Allow-list, not block-list. I enumerate what's permitted rather than trying to block bad verbs. A block-list is one forgotten verb away from a mutation; an allow-list fails closed.

  • One chokepoint. All kubectl execution goes through _run_kubectl. The security boundary is one function you can audit in 30 seconds.

  • Timeouts and clear errors. Calls time out and surface kubectl's stderr instead of hanging or failing silently — the model gets actionable feedback.

What I'd do next

  • Add resource-level scoping (restrict to specific namespaces per connection).

  • Stream large log outputs instead of buffering.

  • Add a small eval that checks the server refuses every mutating verb.

License

MIT — see LICENSE.

Available Tools

5 tools
describe_podA

Show detailed status, events, and configuration for a single pod.

Inputs: name (required), namespace. Returns: result

get_pod_logsB

Fetch the last N lines of logs for a pod (default 100 lines).

Inputs: name (required), tail, namespace. Returns: result

list_deploymentsB

List deployments in a namespace and their ready/up-to-date status.

Inputs: namespace. Returns: result

list_namespacesA

List all namespaces in the cluster.

Inputs: no named parameters. Returns: result

list_podsA

List pods in a namespace (defaults to 'default'). Use 'all' for every namespace.

Inputs: namespace. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct Kubernetes resource or operation: describe_pod for pod details, get_pod_logs for logs, list_deployments for deployments, list_namespaces for namespaces, list_pods for pods. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., list_pods, describe_pod, get_pod_logs) using snake_case throughout, making them predictable and easy to understand.

    Tool Count5/5

    With 5 tools, the server is well-scoped for a read-only Kubernetes interface. It provides essential operations without unnecessary bloat, fitting the typical 3-15 tool range.

    Completeness3/5

    While core pod and deployment listing is covered, the server lacks operations for other common Kubernetes resources like services, nodes, events, or configmaps, which are expected in a read-only toolset.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • 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.

    • The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.

      https://mcp.cortex.io/mcp
    • The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.

    • Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.

      https://aistatusdashboard.com/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for Kubernetes that allows querying cluster information and diagnosing issues through natural language interfaces like Claude.
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides safe, read-only access to Kubernetes resources for debugging and inspection. Built with security in mind, it offers comprehensive cluster visibility without modification capabilities.
      45
      MIT