Operate Rancher-managed Kubernetes through any MCP client — discovery, generic resource access, and curated operator workflows, wrapped in an audit-logged, rate-limited, confirmation-guarded safety model.
Quick start · Tool surface · Architecture · Safety model · Compatibility · Development
Why this exists
Rancher is how real fleets run Kubernetes — and it speaks two APIs (the legacy
Norman /v3 plane and the modern Steve /v1 plane), varies by version, and wraps
every cluster behind its own proxy. Pointing a generic Kubernetes MCP server at it
misses everything Rancher-specific; pointing an agent at raw kubectl gives up
auditability, guardrails, and the management-plane view entirely.
MCP Rancher is built for that reality:
- Capability-aware, not version-naive. It detects what each connected Rancher actually supports instead of assuming. One binary spans 2.6.5 → 2.9.3 with the same tool surface.
- Multi-instance first. Lab, staging, prod — configure them all; mark prod
read_only: trueand every mutation is refused at the config layer, before any guard even has to fire. - Nothing is out of reach. Curated tools cover the common 95%; the generic engine reaches every resource either API plane exposes — even types nobody wrote a tool for yet.
The tool surface
207 tools: 179 read-only · 28 writes · 5 destructive — counted from the
registry itself, not by hand. docs/tool-manifest.json
is generated from the live tool registry (make tool-manifest) and a CI
gate fails the build if it ever drifts from the code. Per-tool descriptions,
safety annotations, and parameters all live there; the narrative registry with
slice tracking is docs/tool-catalog.md.
| Layer | What it does | Examples |
|---|---|---|
| Discovery & schema | Explore what any instance can do | rancher_server_version, rancher_norman_schema_list, rancher_capability_domain_list |
| Generic engine | CRUD + actions + links + watch on any resource, both planes | rancher_steve_resource_list, rancher_norman_resource_action_invoke, rancher_steve_resource_watch |
| Curated reads | Typed, shaped responses across ~25 domains | rancher_pods_list, rancher_deployments_list, rancher_longhorn_volumes_list, rancher_policy_reports_list |
| Curated writes | Guarded mutations | rancher_deployment_scale, rancher_deployment_restart, rancher_cron_job_suspend, rancher_node_cordon, rancher_secret_create |
| Operator rollups | One-call triage | rancher_cluster_health_check, rancher_find_failing_pods, rancher_find_stalled_rollouts, rancher_project_health_summary |
Domains covered: clusters & nodes · projects & namespaces · workloads · pods & services · storage · networking · config & secrets (values masked) · certificates (keys masked) · RBAC · auth & identity · apps & catalogs · logging pipeline · Prometheus monitoring · policy reports · CIS compliance · backup operator · etcd backups · Longhorn · Fleet · provisioning · settings & features · alerts & notifiers.
All 207 stay exposed by default — every tool schema is deferred behind
Claude Code's own search, so a small default would only help other hosts at
the good host's expense. A constrained host (a small local model, a tight
context budget) can opt into a smaller surface via RANCHER_TOOLSETS; see
Toolset profiles under Configuration.
Quick start
Requirements
- uv — it brings its own Python (3.12 or newer)
- A Rancher API token (creating one)
There is nothing to clone or install first: uvx rancher-mcp fetches the
package from PyPI and runs it. Start
with a read-only token, or add RANCHER_READ_ONLY=true, until you have seen
what an agent does with it — see the safety model.
Claude Code
claude mcp add rancher \
-e RANCHER_URL=https://rancher.example.com \
-e RANCHER_TOKEN=token-xxxxx:yyyyyyyyy \
-- uvx rancher-mcp
Claude Desktop, and any client that takes a JSON server entry
{
"mcpServers": {
"rancher": {
"command": "uvx",
"args": ["rancher-mcp"],
"env": {
"RANCHER_URL": "https://rancher.example.com",
"RANCHER_TOKEN": "token-xxxxx:yyyyyyyyy"
}
}
}
}
uvx keeps using the version it first downloaded. Write rancher-mcp@latest
in place of rancher-mcp to pick up a new release.
From source
git clone https://github.com/rex/mcp-rancher.git
cd mcp-rancher
make setup # deps, .env scaffold, pre-commit hooks
$EDITOR .env # set RANCHER_URL + RANCHER_TOKEN
make dev # run the MCP server (stdio)
To point a client at a checkout, use
uv run --directory /path/to/mcp-rancher rancher-mcp in place of
uvx rancher-mcp.
Multiple instances
RANCHER_INSTANCES_JSON='{
"production": {"url": "https://rancher.prod.example.com", "token": "token-a:xxx", "verify_ssl": true, "read_only": true},
"lab": {"url": "https://rancher.lab.example.com", "token": "token-b:yyy", "verify_ssl": false, "read_only": false}
}'
RANCHER_DEFAULT_INSTANCE=production
Every tool takes an optional instance argument. Instances flagged
read_only: true refuse all mutations at the settings layer.
Architecture
flowchart LR
A[MCP client<br/>Claude Code · Claude Desktop · any] -- stdio --> S
subgraph S[rancher-mcp]
direction TB
L1[Discovery & schema<br/>planes · schemas · capabilities]
L2[Generic engine<br/>any resource · both planes<br/>CRUD · actions · links · watch]
L3[Curated tools<br/>typed models · shaped output<br/>next-step hints]
G[Safety layer<br/>read-only guard · confirmation phrases<br/>audit log · rate limit · masking]
L1 --> L2 --> L3
L3 --> G
L2 --> G
end
G -- Norman /v3 --> R1[(Rancher<br/>instance A)]
G -- Steve /v1 + k8s proxy --> R1
G -- Norman + Steve --> R2[(Rancher<br/>instance B)]
Three layers, deliberately separate: discovery tells you what an instance can
do, the generic engine can touch anything it exposes, and curated tools
make the common paths typed, shaped, and self-describing (every response carries
suggested_next_steps). Most curated tools are generated from YAML descriptors
(catalog/curated_tools/) with a drift gate — the editorial decisions live in
descriptors, not boilerplate.
Safety model
Built for the day an agent is pointed at the cluster that pays your salary:
| Guard | Behavior |
|---|---|
| Read-only instances | read_only: true refuses every mutation for that instance before anything is sent — and the HTTP client of a read-only instance sends nothing but reads, so a tool that failed to refuse still could not write |
| Destructive confirmation | Deletes require an explicit typed phrase (e.g. "delete steve namespace foo") — no phrase, no delete |
| Human approval | A phrase the model can type proves the model read it; this proves a person agreed. Two mechanisms, both on for the destructive tools. Any client that supports MCP elicitation is shown a question the server worded — Delete deployment "web" in namespace "shop" on cluster "c-m-abc"? — and the tool does not run unless a person ticks the box and accepts. Claude Code additionally shows its own permission prompt on every call, in every permission mode including bypass (anthropic/requiresUserInteraction). A client that can do neither falls back to the confirmation phrase; nothing is waved through |
| Tool annotations | Every tool declares readOnlyHint / destructiveHint / idempotentHint, so clients can gate UX on them |
| Audit log | Every mutation emits a structured event="audit" record — tool, operation, plane, instance, resource, outcome. Argument names only; values never logged |
| Rate limiting | Token-bucket on writes (default 60/min) — a runaway loop can't machine-gun your API |
| Secret & key masking | Secret values and certificate private keys are structurally absent from curated responses (reveal is an explicit generic-tool opt-in) |
| Structured errors | Guard rejections return typed error_code envelopes agents can branch on — never raw strings |
Compatibility
| Primary target | Rancher 2.9.3 (production-validated) |
| Compatibility floor | Rancher 2.6.5 (kept green via capability detection) |
| API planes | Norman /v3 + Steve /v1 (+ per-cluster Kubernetes proxy) |
| MCP protocol | 2026-07-28, and the older 2025-11-25 handshake for clients that have not moved — one process serves both and the client chooses |
| Transport | stdio |
Capability detection bridges version differences at runtime — no version-pinned builds, no "works on my Rancher." Both targets are exercised by the same test suite, and read paths have been validated live against both a 2.6.5 lab and a 2.9.3 production fleet (validation report).
Configuration
| Variable | Default | Purpose |
|---|---|---|
RANCHER_URL |
— | Rancher server URL (single-instance mode) |
RANCHER_TOKEN |
— | API token (token-xxxxx:yyyyyyyyy) |
RANCHER_VERIFY_SSL |
true |
TLS verification |
RANCHER_INSTANCES_JSON |
— | Multi-instance config (see above) |
RANCHER_DEFAULT_INSTANCE |
first defined | Instance used when a tool call names none |
RANCHER_MCP_SERVER_NAME |
rancher-mcp |
Server identity announced to clients |
RANCHER_MCP_SERVER_DESCRIPTION |
built-in | Server description announced to clients |
RANCHER_MCP_WRITE_RATE_LIMIT_PER_MIN |
60 |
Write rate limit (0 disables) |
RANCHER_TOOLSETS |
all |
Comma-separated toolset profile(s) exposed at startup — see below |
RANCHER_TOOLS |
— | Comma-separated tool names force-included on top of the selected profile(s) |
RANCHER_EXCLUDE_TOOLS |
— | Comma-separated tool names removed, applied last — always wins over RANCHER_TOOLS |
RANCHER_MCP_REQUIRE_APPROVAL_FOR_DESTRUCTIVE |
true |
Require a person's approval for destructive tools: an elicitation prompt in any client that can show one, plus Claude Code's permission prompt on every call. Set false only for an unattended pipeline that legitimately deletes — there a prompt can reach nobody and the call is refused. The confirmation phrase stays either way |
Toolset profiles
The default is all: every tool stays exposed. Claude Code, the primary
host, defers every tool schema behind its own search, so a small default
would only help other hosts at the cost of making the good host worse — this
is a deliberate choice, not an oversight.
RANCHER_TOOLSETS opts a constrained host (a small local model, or a context
budget) into a smaller surface. Values are either a family name — one per
src/rancher_mcp/tools/ module (storage, workloads, pods_services,
rbac, …; see rancher_mcp.toolsets.FAMILY_REGISTRARS for the full list) —
or the cross-family core profile: a ~32-tool triage/orientation set
(rancher_find_*, the health/summary rollups, core list/get pairs, and the
generic rancher_{steve,norman}_resource_{list,get} escape hatches). core
cuts the tools/list payload from 207 tools / ~404 KB to 32 tools / ~78 KB
(~80% smaller). Profiles compose: RANCHER_TOOLSETS=core,storage gives the
triage set plus everything storage-related.
RANCHER_TOOLSETS=core # small triage surface
RANCHER_TOOLSETS=core,storage,workloads # triage + two full families
RANCHER_TOOLS=rancher_secret_get # add one extra tool on top
RANCHER_EXCLUDE_TOOLS=rancher_secret_create # remove one, wins over the above
An unknown profile name fails loudly at startup rather than silently
producing an empty or shrunken surface. Calling a real tool that exists but
isn't in the active profile returns a structured TOOLSET_NOT_ENABLED error
naming the tool, the toolset that would enable it, and the env var to set —
never a bare "unknown tool", which would make a disabled tool indistinguishable
from a typo.
Front-door tools
Because Claude Code defers tool definitions, the model's first Rancher call
normally costs a tool-search round trip. Five tools opt out and load upfront —
the ones that are plausible first calls in a session:
rancher_clusters_health_summary, rancher_cluster_health_check,
rancher_find_failing_pods, rancher_find_unready_nodes and
rancher_resource_events. They carry _meta["anthropic/alwaysLoad"], cost
about 590 tokens of context between them, and a test budgets the set so it
cannot grow by accretion.
Other clients ignore the hint. To defer everything again in Claude Code, set
"alwaysLoad": false on this server's entry in your MCP configuration.
Project status
Shipping and stable for read, triage, and guarded write operations. Honest ledger of what's beyond that:
- Destructive workflows (node drain, etcd/backup restore, cert rotation, cluster upgrade/delete) are roadmap — deliberately staged after real-world read-path mileage. The generic engine + confirmation guard already covers these cases for operators who need them today.
- The Alertmanager routes/silences surface needs an in-cluster API integration and is deferred.
- The full per-version compatibility matrix (Track G) is in progress; the first live validation run covers the read matrix on both targets.
Work is tracked to the tool level: docs/tool-catalog.md
(every tool has a row, every gap a slice ID) and ROADMAP.md.
Development
make help # every target, documented
make validate # codegen drift + manifest drift + architecture + lint + typecheck + tests
make tool-manifest # regenerate docs/tool-manifest.json from the registry
make lab-up # local Rancher 2.6.5 lab (kind + helm), fully scripted
make integration-current # isolated Rancher 2.14.3 end-to-end test run
make live-read-matrix # read-only validation probes against configured instances
make mock-rancher # fixture-backed mock Rancher for provider-config testing
- Local lab — a self-contained Rancher 2.6.5 on kind with a simulated downstream cluster; repo-local kubeconfigs, never touches your machine state.
- Current integration lab — Rancher 2.14.3 on separate Kind clusters and
port
9443; run it serially withmake integration-currentto avoid overlapping Docker resource demand with the legacy lab. - Contract fixtures — sanitized captures from live Rancher committed under
tests/fixtures/;respxpins the HTTP boundary in tests. - Codegen — curated tools are emitted from
catalog/curated_tools/*.ymldescriptors;make check-codegenfails on drift. - Gates — ruff, pyright strict, the test suite with a coverage floor, architecture line-limits, module-shape checks, secret scanning. All fail closed, all wired into pre-commit.
Stack: Python 3.12 · MCP Python SDK 2.x · httpx · Pydantic v2 · structlog · uv
Security
See SECURITY.md for the threat model, token guidance, and how to report vulnerabilities.
License
Metadata
Release files for rancher-mcp 1.77.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rancher_mcp-1.77.0.tar.gz | 292.3 kB | Without provenance | Details for rancher_mcp-1.77.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rancher_mcp-1.77.0-py3-none-any.whl | Python 3 | none | any | Details for rancher_mcp-1.77.0-py3-none-any.whl |
Total release size: 791.0 kB
Release files / rancher_mcp-1.77.0.tar.gz
| Download URL | rancher_mcp-1.77.0.tar.gz |
|---|---|
| Size | 292.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
83118cea976d75623ff514878a59a1b47831771fa4ce0328b026dedc07cd8f8d
|
|
BLAKE2b-256 checksum How to use checksums |
d72917aa851927117d655554a4b2a7f43a9e244ec742ed69db23234fec40479a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rancher_mcp-1.77.0-py3-none-any.whl
| Download URL | rancher_mcp-1.77.0-py3-none-any.whl |
|---|---|
| Size | 498.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8824b33cf9ffafc72e6ef5d59d9274f50b217e202cfa73a07abaac20d081e98a
|
|
BLAKE2b-256 checksum How to use checksums |
64c049c2c000611a30d03f81a5e03a351506e07405e8da78a1ba0d25527dcd2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for rancher-mcp 1.77.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.