io.github.dockndevai/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 for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT