K8s MCP Server README

k8s-mcp-server

Production-ready Kubernetes diagnostics and cluster observability MCP server for AI agents.

What is this?

k8s-mcp-server is a Model Context Protocol (MCP) server providing automated, read-only diagnostic tools for inspecting Kubernetes clusters. It allows AI agents to troubleshoot pod crashes, inspect ingress routes, and analyze cluster-wide warning events safely.

Available Tools

Tool	Category	Description
`get_cluster_nodes`	Infrastructure	Lists nodes, readiness states, roles, and kubelet versions.
`get_pod_diagnostics`	Workloads	Detects abnormal pod phases, restart loops, and CrashLoopBackOffs.
`get_pod_logs`	Observability	Retrieves container stdout/stderr logs with tail limits and crash inspection.
`list_warning_events`	Diagnostics	Aggregates FailedScheduling, FailedMount, and BackOff warning events.
`list_ingresses`	Networking	Audits HTTP routing rules, host headers, and TLS certificates.

Quick Start

Prerequisites

Python 3.11+
Active Kubernetes cluster access (~/.kube/config or in-cluster ServiceAccount)
Read-only RBAC privileges (get, list on core and networking API groups)

Run Locally

bash

git clone https://github.com/akkireddy-challa/k8s-mcp-server.git
cd k8s-mcp-server
pip install -r requirements.txt
python server.py

Claude Desktop Configuration

Add to claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["/path/to/k8s-mcp-server/server.py"],
      "env": {
        "KUBECONFIG": "/Users/<username>/.kube/config"
      }
    }
  }
}

Security Model

Strictly Read-Only: Enforces GET and LIST operations only.
Zero-Secret Exposure: Secrets and config maps are never inspected or surfaced to LLM context.
Flexible Auth: Supports standard ~/.kube/config context or in-cluster pod ServiceAccounts.

License

MIT License. See LICENSE for details.

Built by Akkireddy Challa — Platform Engineer at Telia, Stockholm.