k8s-assistant
Provides tools for interacting with a Kubernetes cluster to diagnose and manage applications, including listing pods, fetching pod logs and events, and restarting deployments with server-side guardrails and RBAC constraints.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| read-only | name, phase, status, restart count |
| read-only | hard cap of 200 lines enforced server-side; log text treated as untrusted data |
| read-only | 20 most recent Warning events |
| destructive | namespace allow-list |
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
Server guardrails: input validation, namespace allow-list, log-line cap, a single write tool that can only restart.
Kubernetes RBAC (k8s/rbac.yaml): the server connects as a dedicated ServiceAccount that can read pods, pod logs and events, and
patchdeployments inshoponly. No secrets, nopods/exec, no delete. Even a bug in the server cannot exceed these permissions.scripts/prove-rbac.shdemonstrates it withkubectl auth can-i.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 |
| create / delete the cluster |
| create Service |
| return to the broken state in under a minute |
| kubeconfig for the |
| show allowed vs denied actions |
| replay the demo with typing delays (fallback if the live run fails) |
| record the replay to |
| 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 |
|
| kubeconfig the server uses |
|
| 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.stagingis 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Troubleshoot enrolled client PCs from your AI client, with human approval and an audit trail.
AI agent security audit: red-team probes plus missing-guardrail review with fixes.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects an AI assistant to local Docker and Kubernetes environments, enabling real-time command execution and log inspection with user approval.-
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to safely observe and troubleshoot Kubernetes workloads, with limited recovery actions like pod deletion and Helm rollbacks, while preventing dangerous modifications.18Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to safely interact with Kubernetes clusters through scoped, redacted tools, with credentials kept local and write operations requiring human approval.30 PyPIApache 2.0