Skip to main content
Glama

Kubernetes Assistant with MCP

A small, readable Model Context Protocol server that lets an AI assistant diagnose a broken application on a local Kubernetes cluster, with guardrails you can explain and audit.

Companion demo for the talk "Build Your Own AI Kubernetes Assistant with MCP".

MCP host (Claude Code / Claude Desktop)
        │  stdio
        ▼
server/server.py ── ServiceAccount token ──▶ kube-apiserver  (RBAC has the final say)
        │
        └── audit.log  (append-only JSON lines)

Features

Tool

Access

Guardrails

list_pods(namespace)

read-only

name, phase, status, restart count

get_pod_logs(pod, namespace, tail=50)

read-only

hard cap of 200 lines enforced server-side; log text treated as untrusted data

get_events(namespace)

read-only

20 most recent Warning events

restart_deployment(name, namespace)

destructive

namespace allow-list {shop, staging}, restart only, server-side dry-run preview, host approval prompt

The diagnose_pod prompt is a runbook: inspect pods, events and logs, then report root cause, evidence and a proposed fix, and ask before any restart.

Related MCP server: K8gentS

Defence in depth

  1. Server guardrails: input validation, namespace allow-list, log-line cap, a single write tool that can only restart.

  2. Kubernetes RBAC (k8s/rbac.yaml): the server connects as a dedicated ServiceAccount that can read pods, pod logs and events, and patch deployments in shop only. No secrets, no pods/exec, no delete. Even a bug in the server cannot exceed these permissions. scripts/prove-rbac.sh demonstrates it with kubectl auth can-i.

  3. Audit trail: every call, including rejections and errors, is appended to audit.log.

Requirements

Docker, kind, kubectl, Python 3.10+, uv. scripts/preflight.sh checks them (and installs missing ones via Homebrew on macOS).

Quick start

./scripts/preflight.sh          # verify tooling
./scripts/setup.sh              # kind cluster, namespaces, demo apps, RBAC, ServiceAccount kubeconfig (idempotent)
uv run python tests/client.py   # exercise every tool and guardrail over stdio
./scripts/register-claude.sh    # register the server with Claude Code (project scope)

Then start claude in this directory and approve the k8s-assistant project server once.

The demo scenario

Namespace shop runs cart and orders-db (healthy) and checkout, which crash-loops because it resolves the wrong database host (connection refused: db:5432). scripts/fix-db.sh creates the missing db Service, after which a restart recovers checkout. The full live script is in DEMO.md.

Scripts

Script

Purpose

setup.sh / teardown.sh

create / delete the cluster

fix-db.sh

create Service db (the fix)

demo-reset.sh

return to the broken state in under a minute

make-kubeconfig.sh

kubeconfig for the mcp-assistant ServiceAccount (short-lived token, git-ignored)

prove-rbac.sh

show allowed vs denied actions

demo-dry-run.sh

replay the demo with typing delays (fallback if the live run fails)

record.sh

record the replay to recordings/

show-audit.sh

pretty-print the audit log

Terminal setup for screen recording: scripts/mac-terminal-setup.md.

Using Claude Desktop

Merge this entry into mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (do not replace the file). Use absolute paths: which uv for the command and pwd for the project directory.

{
  "mcpServers": {
    "k8s-assistant": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["--directory", "/ABS/PATH/k8s-mcp-demo", "run", "python", "server/server.py"],
      "env": { "K8S_MCP_KUBECONFIG": "/ABS/PATH/k8s-mcp-demo/kubeconfig/mcp-assistant.kubeconfig" }
    }
  }
}

Configuration

Variable

Default

Meaning

K8S_MCP_KUBECONFIG

kubeconfig/mcp-assistant.kubeconfig

kubeconfig the server uses

K8S_MCP_AUDIT_LOG

audit.log

audit log path

Dependencies are pinned in pyproject.toml / uv.lock (mcp==1.30.0, kubernetes==36.0.3).

Security notes

  • No secrets are committed; kubeconfig/ holds a short-lived token and is git-ignored.

  • staging is allowed by the server but denied by RBAC. That mismatch is deliberate, to show RBAC is the real boundary.

  • This is a demo for a local kind cluster. Review the permissions before pointing it at anything shared.

License

Apache License 2.0. See LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Connects an AI assistant to local Docker and Kubernetes environments, enabling real-time command execution and log inspection with user approval.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Kubernetes diagnostic agent that provides on-demand root cause analysis and human-in-the-loop remediation via Slack, using LLM reasoning with OPA-bounded security controls.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely observe and troubleshoot Kubernetes workloads, with limited recovery actions like pod deletion and Helm rollbacks, while preventing dangerous modifications.
      18
      Apache 2.0