Rancher MCP Server

English | 中文

Features | Getting Started | Configuration | Tools | Development

Features

A Model Context Protocol (MCP) server for Rancher multi-cluster management.

• Multi-cluster Management: Access Kubernetes clusters through the Rancher API or configured kubeconfig paths
• Kubernetes Resources via Steve API: CRUD operations on any resource type
  • Get/List any resource (Pod, Deployment, Service, ConfigMap, Secret, CRD, etc.)
  • Create resources from JSON manifests
  • Patch resources using JSON Patch (RFC 6902)
  • Delete resources
  • Describe resources with related events (similar to kubectl describe)
  • List and filter Kubernetes events by namespace, object name, and object kind
  • Query container logs with filtering (tail lines, time range, timestamps, keyword search)
  • Multi-pod log aggregation via label selector with time-based sorting
  • View rollout history for Deployments
  • Inspect node state and resource usage
  • Inspect pods with parent workload, metrics, and logs
  • Show dependency/dependent trees for any resource (inspired by kube-lineage)
  • Get all resources (inspired by ketall): List all Kubernetes resources including ConfigMaps, Secrets, RBAC, CRDs
  • Compare resource versions (kubernetes_diff): Show git-style diffs between two resource versions
  • Watch resource changes (kubernetes_watch): Monitor resources and return git-style diffs at regular intervals
  • Resource capacity overview (inspired by kube-capacity): Show cluster resource capacity, requests, limits, and utilization
  • Resource top ranking (kubernetes_top): Rank pods or nodes by CPU/memory usage, requests, limits, or restart count
  • Workload health summary (kubernetes_workload_health): Health overview for Deployments, StatefulSets, and DaemonSets with ready/desired ratios and status derivation
  • Resource summary by group (kubernetes_resource_summary): Aggregate pod resources by namespace or label key with totals for requests/limits
  • Event pattern analysis (kubernetes_event_summary): Group and rank events by reason, kind, and frequency to identify recurring issues
• Rancher Resources via Norman API: List clusters and projects
• Security Controls:
  • read_only: Disables create, patch, and delete operations
  • disable_destructive: Disables delete operations only
  • show_sensitive_data: Global administrator control for sensitive data visibility (default: false)
    • When disabled (default): All sensitive data is masked with ***
    • When enabled: Per-tool showSensitiveData parameter controls visibility
    • Applies to: Kubernetes Secret data and stringData fields
    • Affects tools: kubernetes_get, kubernetes_list, kubernetes_describe
  • allowed_namespaces: Optional per-cluster namespace allowlist. A cluster is restricted only when its array contains names
  • enable_container_exec: Explicit opt-in for pod command execution (default: false, also requires read_only=false)
  • enable_container_file_upload / enable_container_file_download: Explicit opt-in for container file transfer tools; upload also requires read_only=false
• Output Formats: Table, YAML, and JSON
• Output Filters: Remove verbose fields like managedFields from responses
• Pagination: Limit and page parameters for list operations
• Cross-platform: Native binaries for Linux, macOS, Windows, and npm package

Getting Started

Requirements

Configure at least one cluster access method:

• Rancher access: a Rancher server and API credentials (Token or Access Key/Secret Key)
• Direct Kubernetes access: one or more kubeconfig paths

Rancher access and credentials are optional when kubeconfig paths are configured.

Claude Code

claude mcp add rancher -- npx -y @futuretea/rancher-mcp-server@latest \
  --rancher-server-url https://your-rancher-server.com \
  --rancher-token your-token

Arguments after -- are written to your MCP config as-is. The -y flag tells npx to install without prompting, which is required for non-interactive MCP startup. See the VS Code / Cursor section for the equivalent JSON config.

VS Code / Cursor

Add to .vscode/mcp.json or ~/.cursor/mcp.json:

{
  "servers": {
    "rancher": {
      "command": "npx",
      "args": [
        "-y",
        "@futuretea/rancher-mcp-server@latest",
        "--rancher-server-url",
        "https://your-rancher-server.com",
        "--rancher-token",
        "your-token"
      ]
    }
  }
}

Configuration

Configuration can be set via CLI flags, environment variables, or a config file.

Priority (highest to lowest):

1. Command-line flags
2. Environment variables (prefix: RANCHER_MCP_)
3. Configuration file
4. Default values

CLI Options

npx @futuretea/rancher-mcp-server@latest --help

Configuration File

Create config.yaml:

port: 0  # 0 for stdio, or set a port like 8080 for HTTP/SSE

log_level: 5

rancher_server_url: https://your-rancher-server.com

# Authentication: choose exactly one mode.

# Mode 1: Static credentials
# Static bearer token:
rancher_token: your-bearer-token
# Or use Access Key/Secret Key:
# rancher_access_key: your-access-key
# rancher_secret_key: your-secret-key

# Mode 2: Direct per-request token (HTTP/SSE mode only)
# When enabled, the server uses Authorization: Bearer  from each HTTP/SSE
# request. If Authorization is absent, it uses a non-empty raw R_token header instead.
# A present malformed or empty Authorization header never falls back to R_token.
# Static credentials above must be empty.
# rancher_request_token_auth: true

# Mode 3: Rancher OAuth token passthrough (Streamable HTTP /mcp only)
# The client obtains its Rancher access token outside this service. The server
# verifies the Bearer JWT before it calls Rancher and then passes that verified
# token to Rancher APIs. Do not combine this with Modes 1 or 2.
# rancher_oauth_token_auth: true
# rancher_oauth_authorization_server_url: https://rancher.example.com/oidc
# The server loads the JWKS at startup and refreshes it automatically.
# rancher_oauth_jwks_url: https://rancher.example.com/oidc/.well-known/jwks.json
# rancher_oauth_resource_url: https://mcp.example.com

# rancher_tls_insecure: false

# Optional direct Kubernetes cluster source. Each context is exposed as
# kubeconfig:; use cluster_list to discover available IDs.
# When multiple files define the same context, the first file wins.
# kubeconfig_paths:
#   - /etc/rancher-mcp/kubeconfig
#   - /etc/rancher-mcp/extra-kubeconfig

# Optional per-cluster namespace allowlist. A cluster is restricted only when its
# array contains namespace names. A missing field, {}, a missing key, and an empty
# array leave that scope unrestricted. Quote keys that contain a colon.
# allowed_namespaces:
#   c-abc12:
#     - default
#     - app
#   "kubeconfig:production":
#     - app

read_only: true  # default: true
disable_destructive: false

# High-risk container operations are disabled by default.
# enable_container_exec requires read_only: false.
# enable_container_file_upload also requires read_only: false.
enable_container_exec: false
enable_container_file_upload: false
enable_container_file_download: false

# Sensitive Data Control:
# Global administrator setting that controls whether sensitive data can be shown.
# - false (default): All sensitive data is always masked with '***'
# - true: Allows per-tool showSensitiveData parameter to control visibility
# Applies to Kubernetes Secret data and stringData fields.
show_sensitive_data: false

# Reserved compatibility setting; current tool handlers use each tool's format parameter.
list_output: json

# Remove verbose fields from output
output_filters:
  - metadata.managedFields
  - metadata.annotations.kubectl.kubernetes.io/last-applied-configuration

toolsets:
  - kubernetes
  - rancher

# enabled_tools: []
# disabled_tools: []

Start the server with the file explicitly; it is not discovered automatically:

rancher-mcp-server --config ./config.yaml

Kubeconfig cluster source

kubeconfig_paths adds direct Kubernetes contexts without routing requests through Rancher. Files are loaded in order; if more than one file declares the same context, the first file wins. Run cluster_list to obtain IDs such as kubeconfig:production and pass those IDs to Kubernetes tools.

The result of cluster_list includes a source column. Rancher rows use rancher; direct-context rows use kubeconfig and intentionally leave Rancher-only fields empty. project_list remains Rancher-only and rejects kubeconfig: IDs.

Do not combine kubeconfig_paths with rancher_request_token_auth or rancher_oauth_token_auth: kubeconfig credentials belong to the server process, while those modes use caller-scoped Rancher tokens. In HTTP/SSE mode (port > 0), this server has no HTTP authentication for kubeconfig-backed requests. Prefer stdio or restrict network access to trusted callers.

For an MCP client that uses npx, pass the same arguments after the package name: npx -y @futuretea/rancher-mcp-server@latest --config ./config.yaml.

Namespace allowlist

allowed_namespaces limits Kubernetes tools on selected clusters. A cluster is restricted only when its array lists namespace names. On a restricted cluster, naming a namespace outside the list returns an error and does not call the backend. Omitting the namespace returns only listed namespaces. scanNamespace follows the same rule. A listed namespace that no longer exists is skipped instead of failing the query. Node and PersistentVolume stay available. A Namespace object is limited to the listed names. Whether any other resource type is cluster-scoped is resolved the same way the backend resolves it: built-in types are known statically, and custom resources are checked against the cluster’s API discovery.

--allowed-namespaces replaces RANCHER_MCP_ALLOWED_NAMESPACES, which replaces the file value. The CLI and environment value is one JSON object, not a comma-separated list. An empty string, invalid JSON, a whitespace-only name, or a duplicate name fails startup.

When the file value is effective, duplicate allowed_namespaces top-level keys that differ only by case also fail startup. A CLI or environment object still replaces the file value as a whole.

rancher-mcp-server --allowed-namespaces '{"c-abc12":["default","app"]}'

Environment Variables

Use RANCHER_MCP_ prefix with underscores:

RANCHER_MCP_PORT=8080
RANCHER_MCP_RANCHER_SERVER_URL=https://rancher.example.com
RANCHER_MCP_RANCHER_TOKEN=your-token
RANCHER_MCP_KUBECONFIG_PATHS=/etc/rancher-mcp/kubeconfig,/etc/rancher-mcp/extra-kubeconfig
RANCHER_MCP_ALLOWED_NAMESPACES='{"c-abc12":["default","app"]}'
RANCHER_MCP_READ_ONLY=true
RANCHER_MCP_SHOW_SENSITIVE_DATA=false  # Global admin control for sensitive data
RANCHER_MCP_ENABLE_CONTAINER_EXEC=false

RANCHER_MCP_KUBECONFIG_PATHS uses a comma-separated ordered list, matching kubeconfig_paths. When multiple files define the same context, the first path wins.

For Rancher OAuth token passthrough, configure the OAuth settings with the same prefix:

RANCHER_MCP_RANCHER_OAUTH_TOKEN_AUTH=true
RANCHER_MCP_RANCHER_OAUTH_AUTHORIZATION_SERVER_URL=https://rancher.example.com/oidc
RANCHER_MCP_RANCHER_OAUTH_JWKS_URL=https://rancher.example.com/oidc/.well-known/jwks.json
RANCHER_MCP_RANCHER_OAUTH_RESOURCE_URL=https://mcp.example.com

HTTP/SSE Mode

Run with a port number for network access:

rancher-mcp-server --port 8080 \
  --rancher-server-url https://your-rancher-server.com \
  --rancher-token your-token

Endpoints:

• /healthz - Health check
• /mcp - Streamable HTTP endpoint
• /sse - Server-Sent Events endpoint
• /message - Message endpoint for SSE clients

In Rancher OAuth token passthrough mode, /mcp and /.well-known/oauth-protected-resource are the MCP transport routes. /sse and /message return 404 in that mode; /healthz and /debug/vars remain available.

With a public URL behind a proxy:

rancher-mcp-server --port 8080 \
  --sse-base-url https://your-domain.com:8080 \
  --rancher-server-url https://your-rancher-server.com \
  --rancher-token your-token

Per-Request Rancher Token Authentication

When running in HTTP/SSE mode behind a gateway that authenticates users, you can use --rancher-request-token-auth so the server does not store static Rancher credentials. It uses Authorization: Bearer when that field is present; otherwise, it uses a non-empty raw R_token header for the Rancher API.

Requirements:

• HTTP/SSE mode only (--port must be greater than 0; incompatible with stdio mode)
• The upstream gateway or proxy must forward either Authorization or R_token on every request to /mcp, /sse, and /message; a present malformed or empty Authorization field blocks R_token fallback
• Cannot be combined with --rancher-token, --rancher-access-key, or --rancher-secret-key

Example:

rancher-mcp-server --port 8080 \
  --rancher-request-token-auth \
  --rancher-server-url https://your-rancher-server.com

Gateway Examples

The upstream gateway must forward the selected request-token header. Minimal examples use Authorization:

nginx:

location ~ ^/(mcp|sse|message)$ {
    proxy_pass http://rancher-mcp-server:8080;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

This route preserves the original request path and applies to every transport route required by direct per-request token authentication.

Traefik ForwardAuth:

http:
  middlewares:
    rancher-mcp-auth:
      forwardAuth:
        address: "https://auth.example.com/verify"
        authResponseHeaders:
          - Authorization

Use this only when the authentication service returns a valid Authorization: Bearer response header. Traefik then copies that header to the upstream request. If the incoming request already carries the Rancher Bearer token, do not overwrite it with a static header value.

Rancher OAuth Token Passthrough Authentication

Rancher OAuth token passthrough is an opt-in alternative to static credentials and direct per-request tokens. An MCP client obtains a Rancher access token outside this service, sends it as Authorization: Bearer to /mcp, and the server verifies its RS256 signature, issuer, present time claims with a ten-second leeway, and the offline_access and rancher:mcp scopes before constructing Rancher clients. Audience is not enforced and expiration is not required. Invalid or missing tokens receive 401 Unauthorized with a WWW-Authenticate resource-metadata challenge and make no Rancher API calls.

Use it only in Streamable HTTP mode:

rancher-mcp-server --port 8080 \
  --rancher-server-url https://rancher.example.com \
  --rancher-oauth-token-auth \
  --rancher-oauth-authorization-server-url https://rancher.example.com/oidc \
  --rancher-oauth-jwks-url https://rancher.example.com/oidc/.well-known/jwks.json \
  --rancher-oauth-resource-url https://mcp.example.com

Requirements and limits:

• --rancher-oauth-token-auth and the three OAuth URLs are required. A Rancher server URL is also required. OAuth mode cannot be combined with static credentials or --rancher-request-token-auth, and it is rejected in stdio mode.
• The removed audience YAML key and derived environment name are not newly rejected; current configuration loading ignores unknown legacy inputs.
• The resource URL must be the root public URL. Path-mounted deployments are unsupported. The server does not validate URL format, URL path, or HTTPS; deployment owns those settings.
• OAuth mode registers /mcp and /.well-known/oauth-protected-resource as its MCP transport routes. It does not provide OAuth SSE or session-principal state, so /sse and /message return 404; /healthz and /debug/vars remain available.
• This service never reads, forwards, stores, or logs Rancher browser cookies such as R_SESS. It does not implement authorization-code exchange, token exchange, refresh tokens, or dynamic client registration.
• The server loads the JWKS during startup and fails to start unless it contains a usable RS256 signature-verification key. It refreshes the JWKS hourly; an unknown key ID can trigger an additional refresh, rate-limited to once every five minutes. A failed or unusable refresh keeps the last known-good keyset. A successful refresh immediately removes keys no longer published by the authorization server.
• This is an explicitly accepted Rancher-token passthrough mode. It provides reference-compatible metadata and a challenge, but does not claim generic MCP OAuth or RFC 9728 interoperability.

Rancher Version Support

Which authentication modes work with which Rancher versions:

OAuth passthrough prerequisites on 2.14 and later:

• The oidc-provider feature must be enabled. It is on by default only on Rancher Prime; community installations enable it manually, and Rancher restarts once.
• The OIDCClient must allow the scopes this server requires. With the default required scope set the client needs offline_access and rancher:mcp, and Rancher issues rancher:mcp only when it is listed in OIDCClient.spec.scopes. A default-configured client issues only openid, profile, and offline_access, which the server rejects.
• The server-url setting must be configured. Without it, issued tokens carry a relative /oidc issuer that no external verifier can match.

Rows for 2.11 and earlier and for 2.12 are based on Rancher source analysis. The 2.13.3, 2.14.3, and 2.15.1 behaviors are covered by the integration suite described under Test.

Tools and Functionalities

Sensitive Data Protection

The server uses a two-tier security model for Secret resources:

1. Global flag --show-sensitive-data (default: false): When disabled, all Secret data and stringData fields are always masked with ***, regardless of per-tool parameters. When enabled, per-tool control is allowed.
2. Per-tool parameter showSensitiveData (default: false): Only takes effect when the global flag is enabled. Controls visibility per call.

Affected tools: kubernetes_get, kubernetes_list, kubernetes_describe.

See Configuration for setup examples.

# --show-sensitive-data=false (default): always masked
apiVersion: v1
kind: Secret
data:
  password: "***"

# --show-sensitive-data=true + showSensitiveData: true
apiVersion: v1
kind: Secret
data:
  password: ""

Tools are organized into toolsets. Use --toolsets to enable specific sets or --enabled-tools/--disabled-tools for fine-grained control.

High-Risk Container Operations

Container exec and file transfer tools are disabled by default and must be explicitly enabled:

kubernetes_exec accepts an argv-style command array (no stdin, no TTY) and returns exitCode, stdout, and stderr. The file transfer tools require tar in the container and respect --max-file-size (default: 10Mi).

Enable uploads with both --read-only=false and --enable-container-file-upload. Enable downloads with --enable-container-file-download.

See the kubernetes tools section for full parameter documentation.

Toolsets

kubernetes

rancher

Development

Prerequisites

• Go 1.26.0+
• Access to a Rancher server (only for Rancher integration testing; kubeconfig-only operation does not require Rancher access)

Build

make build

Test

make test        # unit tests only, no Docker required

Integration tests start real Rancher containers with Docker and exercise the built server against them. They need Docker, several minutes per version, and enough memory for one Rancher container at a time:

go test -tags=integration -timeout 45m ./test/integration/...                       # 2.13.3, 2.14.3, 2.15.1
RANCHER_TEST_VERSIONS=2.14.3 go test -tags=integration -timeout 30m ./test/integration/...

Set RANCHER_TEST_KEEP=1 to keep the Rancher containers for inspection. The same suite runs from the Integration GitHub Actions workflow.

Lint

make lint        # Run golangci-lint
make format      # Auto-format code

Run Locally

make build
./rancher-mcp-server \
  --rancher-server-url https://your-rancher-server.com \
  --rancher-token your-token

Debug with MCP Inspector

npx @modelcontextprotocol/inspector@latest $(pwd)/rancher-mcp-server

Contributing

See CONTRIBUTING.md for development setup, project structure, and pull request guidelines.

Support

• GitHub Issues
• Run rancher-mcp-server --help to inspect the supported configuration flags.

License

Apache-2.0