io.github.kubeleash/kubeleash

Guardrails for AI agents on your cluster. kubeleash is a local MCP 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

_{Install launches the local <code>kubeleash</code> binary — get it via <code>brew</code>, <code>go install</code>, or the container (see <a href="#install">Install</a>). VS Code installs in one click; Cursor & Claude open the <a href="#install">setup steps</a> (GitHub strips the <code>cursor://</code> 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

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 for a fuller, commented policy (read-only prod, broader staging, namespace-scoped dev).

Quickstart

Install it (Homebrew shown — see Install for go install and the container), then exercise a policy without touching any cluster:

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). kubeleash speaks MCP over stdio, so it's launched by your client, not run as a daemon.

Install

All channels run kubeleash locally over stdio — your client launches the binary; nothing is hosted. kubeleash is listed in the official MCP Registry 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 are the fastest path (they need the kubeleash binary on PATH — see Manual). Other clients:

Claude Code — this repo is its own plugin marketplace:

/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 and double-click it; the bundle ships the binary and prompts you for the policy and kubeconfig.

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

# 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):

// 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 · Contributing · Security & threat model · Code of Conduct
• License: Apache-2.0