
mcp-kubernetes
io.github.dockndevai/mcp-kubernetes
Kubernetes monitoring & ops for AI agents — safe-by-default access modes and guards.
Documentation
mcp-kubernetes
A Model Context Protocol server for Kubernetes. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) inspect and operate Kubernetes clusters across multiple contexts — with behaviour controlled entirely by flags.
The design goal is safe by default: it starts read-only, can be scoped to an allowlist of namespaces and contexts, protects system namespaces from mutation, and gates the dangerous operations (delete, apply, exec) behind explicit opt-ins.
Features
- Multi-cluster — every tool accepts an optional
context; scope which contexts are usable with an allowlist. - Access modes —
read-only→read-write→admin, layered so a mode never exposes tools above its level. - Security flags — namespace allowlist, protected namespaces, context allowlist, plus independent opt-ins for delete / apply / exec, dry-run, and JSON audit logging (see below).
- Standard auth — uses your kube-config (or in-cluster service account). No credentials are stored by the server.
Security model
| Concern | Flag | Default | Effect |
|---|---|---|---|
| What can the server do at all? | K8S_MODE | read-only | read-only exposes only reads; read-write adds mutations; admin adds destructive tools. Tools above the mode are never registered. |
| Which namespaces are in scope? | K8S_NAMESPACE_ALLOWLIST | (all) | When set, any operation on a namespace outside the list is refused. For a Namespace object the check is on its name; with no namespace given, a namespaced kind is checked against the context's default namespace. |
| Which namespaces are read-only forever? | K8S_PROTECTED_NAMESPACES | kube-system,kube-public,kube-node-lease | Can be read but never mutated or deleted, regardless of mode. |
| Which clusters are reachable? | K8S_CONTEXT_ALLOWLIST | (all) | When set, only these kube-config contexts may be targeted. |
| Can it delete? | K8S_ALLOW_DELETE | false | delete_resource needs this and admin mode. |
| Can it apply manifests? | K8S_ALLOW_APPLY | false | apply_manifest needs this and read-write mode. |
| Can it exec into pods? | K8S_ALLOW_EXEC | false | exec_in_pod needs this and admin mode; the tool isn't even registered otherwise. |
| Preview without touching the cluster | K8S_DRY_RUN | false | Write/admin tools validate + log intent, then return without calling the API. |
| Audit trail | K8S_AUDIT_LOG | true | Emits a JSON line to stderr per guarded operation (ALLOW / DENY / DRY_RUN). |
| Log redaction | K8S_REDACT_LOGS | true | get_pod_logs and exec_in_pod (stdout/stderr) output is scrubbed of credential-shaped text (PEM private keys, password=/token: style pairs, Authorization/Bearer values, URL passwords, JWTs and service-account tokens, AWS/GCP/GitHub/Slack/... key shapes) before it reaches the model. Best-effort heuristics, not a guarantee (a bare random password is not caught); set false to return raw output. See SECURITY.md for exactly what is and is not caught. |
| Object redaction | K8S_REDACT_OBJECTS | true | get_pod / get_resource / list_events (and API error text) mask credential-shaped content that is not in a Secret: env values whose variable name looks secret (DB_PASSWORD, API_KEY, *_TOKEN, *_DSN, ... in pods and in every pod template: Deployments, StatefulSets, Jobs, CronJobs, ...; valueFrom references stay visible), ConfigMap entries with secret-shaped keys or credential-looking values, Route tls.key, command-line --password x arguments, URL passwords, and the copy of all of it in the last-applied-configuration annotation. Best-effort, by name: a credential under an innocuous name is not caught. Set false to return these objects unchanged. Secret values are always redacted and not affected by this setting. See SECURITY.md. |
| Interactive confirmation | (automatic) | — | Destructive & high-impact actions (delete_resource, exec_in_pod, apply_manifest, scaling a deployment to 0) prompt the human to approve via MCP elicitation before running. The prompt shows the tool, the exact arguments and a fingerprint; the target's uid@resourceVersion is pinned across the prompt and the action is refused if it changed; a prompt nobody answers is a refusal. Deleting a namespace also asks the human to type its name. |
| Require a human | K8S_REQUIRE_HUMAN_APPROVAL | false | When true, destructive ops are refused if the client cannot elicit (instead of falling back to the *_ALLOW_* gate alone). |
The layers are independent — e.g. admin mode with all three opt-ins false can restart and scale deployments but can neither delete resources nor exec into pods.
Tools
Read (read-only+): list_contexts, list_namespaces, list_pods, get_pod, get_pod_logs, list_deployments, list_services, list_nodes, list_events, get_resource
Write (read-write+): scale_deployment, restart_deployment, set_deployment_image, create_namespace, apply_manifest (needs K8S_ALLOW_APPLY)
Admin (admin): delete_resource (needs K8S_ALLOW_DELETE), exec_in_pod (needs K8S_ALLOW_EXEC)
Optional AI risk guard. Set K8S_GUARD_MODE=monitor|enforce to have delete_resource, exec_in_pod and apply_manifest consult a local laya-guard daemon (pipx install laya-guard && laya-guard) that classifies the operation allow/confirm/block before it runs. Runs after the delete/exec/apply gates; only tightens, never grants; fails closed.
Quickstart — add to your agent
Published on npm as @dockndevai/mcp-kubernetes. No clone or build needed — your MCP client runs it on demand with npx. Start in read-only mode; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.
Claude Code (CLI)
claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetes
Claude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"kubernetes": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-kubernetes"
],
"env": {
"KUBECONFIG_PATH": "/Users/you/.kube/config",
"K8S_MODE": "read-only"
}
}
}
}
OpenAI Codex CLI — in ~/.codex/config.toml:
[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }
VS Code (GitHub Copilot, Agent mode) — in .vscode/mcp.json:
{
"servers": {
"kubernetes": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-kubernetes"
],
"env": {
"KUBECONFIG_PATH": "/Users/you/.kube/config",
"K8S_MODE": "read-only"
}
}
}
}
Run from source (development)
Prefer the published package above. To run from a clone:
npm install
npm run build
node dist/index.js # with the environment variables set
Develop
npm run dev # watch mode
npm test # unit tests for the security policy
npm run typecheck
Publishing
This server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See PUBLISHING.md for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.
License
MIT
@dockndevai/mcp-kubernetesnpm install @dockndevai/mcp-kubernetesRelated Servers
io.github.dockndevai/mcp-android
Control Android devices over ADB from AI agents — safe-by-default, read-only by default, audited.
io.github.dockndevai/mcp-azure
Azure Resource Manager inventory & ops for AI agents — governed, confirmation-gated.
io.github.dockndevai/mcp-azure-devops
Azure DevOps boards, repos, pipelines & projects for AI agents — governed.