MCP Kubernetes

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

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](PUBLISHING.md) for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT