io.github.kubeleash/kubeleash
Kubernetes MCP server with RBAC-style, context-scoped guardrails for AI agents.
Open source Open in the app JSON README (API)
About
Kubernetes MCP server with RBAC-style, context-scoped guardrails for AI agents.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- kubeleash
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Stars
- 1
- Last push
- 2026-05-27T17:39:20Z
- Repository state
- ativo
- Language
- Go
- License
- Apache-2.0
- Added
- 2026-08-29 04:00:22
- Updated
- 2026-08-29 04:00:22
- Origin id
io.github.kubeleash/kubeleash
README
<div align="center">
<img src="assets/avatar.png" alt="kubeleash logo" width="132" height="132" />
<h1>kubeleash</h1>
<p><strong>Point it at your over-privileged kubeconfig — it still can't nuke prod.</strong></p>
</div>
[](https://github.com/kubeleash/kubeleash/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/kubeleash/kubeleash)
[](https://scorecard.dev/viewer/?uri=github.com/kubeleash/kubeleash)
[](LICENSE)
[](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**.
<div align="center">
### Add kubeleash to your AI client
[](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) [](#install) [](#install)
<sub>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).</sub>
</div>
## 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`](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 <path>` | Policy file. **Required** (or set `K8S_MCP_POLICY`); with neither, kubeleash refuses to start — default-deny never fails open. |
| `--kubeconfig <path>` | 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 <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.
<details>
<summary>Raw Cursor / VS Code deeplink URLs (if a button doesn't fire)</summary>
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
```
</details>
### 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](docs/design.md) · [Contributing](CONTRIBUTING.md) ·
[Security & threat model](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
- License: [Apache-2.0](LICENSE)