# kubeleash [Health: Active] **Category:** ☁️ Cloud Platforms **Repository:** https://github.com/kubeleash/kubeleash **GitHub Stars:** 1 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/kubeleash ## Description Kubernetes MCP server with RBAC-style, context-scoped guardrails for AI agents. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "kubeleash": { "command": "npx", "args": ["-y","kubeleash"] } } ``` ## Documentation & README
kubeleash logo

kubeleash

Point it at your over-privileged kubeconfig — it still can't nuke prod.

[![CI](https://github.com/kubeleash/kubeleash/actions/workflows/ci.yml/badge.svg)](https://github.com/kubeleash/kubeleash/actions/workflows/ci.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/kubeleash/kubeleash)](https://goreportcard.com/report/github.com/kubeleash/kubeleash) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kubeleash/kubeleash/badge)](https://scorecard.dev/viewer/?uri=github.com/kubeleash/kubeleash) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Release](https://img.shields.io/github/v/release/kubeleash/kubeleash?sort=semver)](https://github.com/kubeleash/kubeleash/releases/latest) **Guardrails for AI agents on your cluster.** kubeleash is a local [MCP](https://modelcontextprotocol.io) server for Kubernetes whose differentiator is RBAC-style, *context-scoped* access control. Point it at a kubeconfig — even a cluster-admin one — and a local policy file constrains what the agent can actually do, **per kube context**, with destructive actions gated **before any call reaches the cluster**.
### Add kubeleash to your AI client [![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=kubeleash&config=%7B%22name%22%3A%22kubeleash%22%2C%22command%22%3A%22kubeleash%22%2C%22args%22%3A%5B%22--policy%22%2C%22%24%7Binput%3ApolicyPath%7D%22%5D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22policyPath%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Path%20to%20your%20kubeleash%20policy.yaml%22%7D%5D%7D)   [![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-0098FF?style=for-the-badge&logo=cursor&logoColor=white)](#install)   [![Claude Code / Desktop](https://img.shields.io/badge/Add%20to-Claude-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](#install) Install launches the local kubeleash binary — get it via brew, go install, or the container (see Install). VS Code installs in one click; Cursor & Claude open the setup steps (GitHub strips the cursor:// one-click link, so it lives there as copy-paste).
## Why Most Kubernetes MCP servers inherit the kubeconfig's permissions wholesale — whatever the credentials grant, the agent can do. kubeleash adds three things native RBAC can't express for this use case: - **Constrain the agent independently of the credentials.** Effective access is always `kubeconfig-grants ∩ policy-allows` — kubeleash only ever *subtracts*. - **Context-aware guardrails.** Policy varies by context (prod vs staging vs dev); native RBAC is per-cluster. - **Block destructive verbs** (`delete`/`exec`/…) as a safety net against agent mistakes and prompt injection. ## What kubeleash enforces kubeleash governs only the calls routed **through** it. It provides a hard guarantee when it is the agent's *sole* path to the cluster. An agent that also has shell access (raw `kubectl`, `oc`, the API) can step around it, so in a shell-enabled assistant kubeleash is advisory — pair it with the `using-kubeleash` skill, which instructs the agent to stop (not reach for kubectl) when the leash is unavailable. ## Policy in 10 seconds ```yaml policies: - contexts: ".*prod.*" # regex over the active context name allow: resources: ["*"] verbs: [get, list, watch] # read-only in prod deny: verbs: [exec] # never, regardless of credentials ``` Deny wins. Default deny. A broken policy refuses to start — it never fails open. See [`examples/policy.yaml`](https://github.com/kubeleash/kubeleash/blob/HEAD/examples/policy.yaml) for a fuller, commented policy (read-only prod, broader staging, namespace-scoped dev). ## Quickstart Install it (Homebrew shown — see [Install](#install) for `go install` and the container), then exercise a policy without touching any cluster: ```bash brew install kubeleash/tap/kubeleash # Grab the commented example policy: curl -fsSL https://raw.githubusercontent.com/kubeleash/kubeleash/main/examples/policy.yaml -o policy.yaml # See how kubeleash validates and normalizes a policy (no cluster needed): kubeleash --policy policy.yaml --print-effective-policy # Try it without touching any cluster — every decision is logged, nothing runs: kubeleash --policy policy.yaml --dry-run ``` Prefer source? `git clone https://github.com/kubeleash/kubeleash && cd kubeleash && go build -o kubeleash ./cmd/kubeleash` (Go 1.26+). Then point an MCP client at it (see [below](#use-it-as-an-mcp-server)). kubeleash speaks MCP over stdio, so it's launched by your client, not run as a daemon. | Flag | Purpose | |------|---------| | `--policy ` | Policy file. **Required** (or set `K8S_MCP_POLICY`); with neither, kubeleash refuses to start — default-deny never fails open. | | `--kubeconfig ` | Explicit kubeconfig. Omit to use the standard client-go rules (`$KUBECONFIG`, `~/.kube/config`). | | `--dry-run` | Evaluate + log every decision, but never execute against a cluster. | | `--print-effective-policy` | Print the resolved/normalized rules and exit. | | `--log-level ` | `debug` / `info` / `warn` / `error` (default `info`). The audit log is JSON on **stderr** (stdout is the MCP transport). | | `--version` | Print version, commit, and build date. | ## Install All channels run kubeleash **locally over stdio** — your client launches the binary; nothing is hosted. kubeleash is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.kubeleash/kubeleash`, so registry-aware clients can discover it too. ### One-click The **Add to Cursor / VS Code** buttons [at the top](#add-kubeleash-to-your-ai-client) are the fastest path (they need the `kubeleash` binary on PATH — see [Manual](#manual)). Other clients: **Claude Code** — this repo is its own plugin marketplace: ```shell /plugin marketplace add kubeleash/kubeleash /plugin install kubeleash@kubeleash ``` No separate install step: on first run the plugin uses a `kubeleash` already on your PATH, or otherwise downloads the matching release binary (verifying its checksum) and caches it. Safe by default — no policy authoring required first: if you have no policy at `~/.kubeleash/policy.yaml`, the plugin writes a **read-only starter** there on first run (allow `get`/`list`/`watch`, deny `exec`/`delete`). Review and widen it to grant more access. (This convenience is the plugin's only; the raw binary still **requires** an explicit `--policy` and refuses to start without one.) The plugin also ships two skills — `using-kubeleash` (how an agent should query and act through the gated tools) and `authoring-kubeleash-policy` (how to write the policy) — so the agent understands the guardrails, not just the tool list. **Claude Desktop** — download `kubeleash.mcpb` from the [releases page](https://github.com/kubeleash/kubeleash/releases) and double-click it; the bundle ships the binary and prompts you for the policy and kubeconfig.
Raw Cursor / VS Code deeplink URLs (if a button doesn't fire) Cursor (can't prompt — edit the placeholder path afterward in *Settings → MCP*). Decodes to `{"command":"kubeleash","args":["--policy","/absolute/path/to/policy.yaml"]}`: ``` cursor://anysphere.cursor-deeplink/mcp/install?name=kubeleash&config=eyJjb21tYW5kIjoia3ViZWxlYXNoIiwiYXJncyI6WyItLXBvbGljeSIsIi9hYnNvbHV0ZS9wYXRoL3RvL3BvbGljeS55YW1sIl19 ``` VS Code (prompts for the policy path): ``` vscode:mcp/install?%7B%22name%22%3A%22kubeleash%22%2C%22command%22%3A%22kubeleash%22%2C%22args%22%3A%5B%22--policy%22%2C%22%24%7Binput%3ApolicyPath%7D%22%5D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22policyPath%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Path%20to%20your%20kubeleash%20policy.yaml%22%7D%5D%7D ```
### Manual ```bash # Homebrew brew install kubeleash/tap/kubeleash # Go go install github.com/kubeleash/kubeleash/cmd/kubeleash@latest # Container (great for running the MCP server sandboxed) docker run --rm -i -v ~/.kube:/root/.kube:ro -v ./policy.yaml:/policy.yaml:ro \ ghcr.io/kubeleash/kubeleash --policy /policy.yaml ``` > kubeleash runs **locally over stdio** and talks only to your clusters. There > is intentionally **no remote/hosted URL connector** — it would mean handing > your cluster credentials to a third party. ## Use it as an MCP server kubeleash exposes 8 generic, GVK-agnostic tools (`k8s_list`, `k8s_get`, `k8s_apply`, `k8s_delete`, `k8s_logs`, `k8s_exec`, `k8s_scale`, and `k8s_capabilities`) that work for any resource, including CRDs. Every call is checked against your policy and recorded to a JSON audit log on stderr (stdout is the MCP transport). It speaks MCP over stdio — point your client at the binary (or container): ```jsonc // Claude Desktop / Cursor / VS Code MCP config { "mcpServers": { "kubeleash": { "command": "kubeleash", "args": ["--policy", "/absolute/path/to/policy.yaml"], "env": { "KUBECONFIG": "/absolute/path/to/kubeconfig" } } } } ``` ## Privacy **Zero telemetry. No phone-home. Local-only by design.** kubeleash talks only to the Kubernetes API servers you point it at — there is intentionally no remote or hosted connector to route your cluster credentials through. That's a feature, not a gap: you run it against real clusters with privileged credentials, so nothing should sit between the agent and your API server but the leash. ## Project - [Design](https://github.com/kubeleash/kubeleash/blob/HEAD/docs/design.md) · [Contributing](https://github.com/kubeleash/kubeleash/blob/HEAD/CONTRIBUTING.md) · [Security & threat model](https://github.com/kubeleash/kubeleash/blob/HEAD/SECURITY.md) · [Code of Conduct](https://github.com/kubeleash/kubeleash/blob/HEAD/CODE_OF_CONDUCT.md) - License: [Apache-2.0](https://github.com/kubeleash/kubeleash/blob/HEAD/LICENSE)