Rancher MCP Server

Features | Getting Started | Configuration | Tools | Development

Features

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

• Multi-cluster Management: Access multiple Kubernetes clusters through Rancher API
• 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
  • Analyze node health 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
• 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
• 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

• Access to a Rancher server
• Rancher API credentials (Token or Access Key/Secret Key)

Claude Code

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

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

| Option | Description | Default | |--------|-------------|---------| | --config | Config file path (YAML) | | | --port | Port for HTTP/SSE mode (0 = stdio mode) | 0 | | --sse-base-url | Public base URL for SSE endpoint | | | --log-level | Log level (0-9) | 5 | | --rancher-server-url | Rancher server URL | | | --rancher-token | Rancher bearer token | | | --rancher-access-key | Rancher access key | | | --rancher-secret-key | Rancher secret key | | | --rancher-tls-insecure | Skip TLS verification | false | | --read-only | Disable write operations | true | | --disable-destructive | Disable delete operations | false | | --show-sensitive-data | Global admin flag to allow sensitive data visibility | false | | --list-output | Output format (json, table, yaml) | json | | --output-filters | Fields to remove from output | metadata.managedFields | | --toolsets | Toolsets to enable | kubernetes,rancher | | --enabled-tools | Specific tools to enable | | | --disabled-tools | Specific tools to disable | |

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
rancher_token: your-bearer-token
# Or use Access Key/Secret Key:
# rancher_access_key: your-access-key
# rancher_secret_key: your-secret-key
# rancher_tls_insecure: false

read_only: true  # default: true
disable_destructive: 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

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: []

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_READ_ONLY=true
RANCHER_MCP_SHOW_SENSITIVE_DATA=false  # Global admin control for sensitive data

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

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

Tools and Functionalities

Sensitive Data Protection

The server provides a two-tier security control for handling sensitive Kubernetes resources (currently Secrets):

Global Administrator Control

The --show-sensitive-data flag (default: false) is a global administrator setting that determines whether sensitive data can ever be revealed:

• Disabled (default: false): All sensitive data is always masked with ***, regardless of per-tool parameters

  • Secret data and stringData fields are masked
  • Provides maximum security by preventing any accidental data exposure
  • Recommended for production environments

• Enabled (true): Allows per-tool showSensitiveData parameter to control visibility

  • Each tool call can choose whether to show or mask sensitive data
  • Useful for troubleshooting and administrative tasks
  • Requires explicit per-call parameter to reveal data

Per-Tool Parameter Control

When global --show-sensitive-data is enabled, tools that access sensitive resources accept a showSensitiveData parameter:

• showSensitiveData: false (default): Masks sensitive fields with ***
• showSensitiveData: true: Shows actual values

Affected Tools:

• kubernetes_get: Get individual resources including Secrets
• kubernetes_list: List resources including Secrets
• kubernetes_describe: Describe resources with events

Example Behavior:

# Global flag disabled (--show-sensitive-data=false)
# Secret data is ALWAYS masked, regardless of per-tool parameter
apiVersion: v1
kind: Secret
data:
  password: "***"  # Always masked
  token: "***"     # Always masked

# Global flag enabled (--show-sensitive-data=true)
# Per-tool parameter controls visibility:

# With showSensitiveData: false (default)
apiVersion: v1
kind: Secret
data:
  password: "***"  # Masked
  token: "***"     # Masked

# With showSensitiveData: true
apiVersion: v1
kind: Secret
data:
  password: "<base64-encoded-value>"  # Actual base64 value shown
  token: "<base64-encoded-value>"     # Actual base64 value shown

Configuration Examples:

# Maximum security (production recommended)
rancher-mcp-server --show-sensitive-data=false  # or omit (default)

# Allow administrators to reveal data when needed
rancher-mcp-server --show-sensitive-data=true

# config.yaml
show_sensitive_data: false  # Production: always mask
# show_sensitive_data: true  # Development: allow per-tool control

# Environment variable
RANCHER_MCP_SHOW_SENSITIVE_DATA=false

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

Toolsets

| Toolset | API | Description | |---------|-----|-------------| | kubernetes | Steve | Kubernetes CRUD operations for any resource type | | rancher | Norman | Cluster and project listing |

kubernetes

Show Kubernetes cluster resource capacity, requests, limits, and utilization. Similar to kube-capacity CLI tool.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | pods | boolean | No | Include individual pod resources in the output (default: false) | | containers | boolean | No | Include individual container resources in the output (implies pods=true) (default: false) | | util | boolean | No | Include actual resource utilization from metrics-server (requires metrics-server) (default: false) | | available | boolean | No | Show raw available capacity instead of percentages (default: false) | | podCount | boolean | No | Include pod counts for each node and the whole cluster (default: false) | | showLabels | boolean | No | Include node labels in the output (default: false) | | hideRequests | boolean | No | Hide request columns from output (default: false) | | hideLimits | boolean | No | Hide limit columns from output (default: false) | | namespace | string | No | Filter by namespace (empty for all namespaces) | | labelSelector | string | No | Filter pods by label selector (e.g., "app=nginx,env=prod") | | nodeLabelSelector | string | No | Filter nodes by label selector (e.g., "node-role.kubernetes.io/worker=true") | | namespaceLabelSelector | string | No | Filter namespaces by label selector (e.g., "env=production") | | nodeTaints | string | No | Filter nodes by taints. Use 'key=value:effect' to include, 'key=value:effect-' to exclude. Multiple taints can be separated by comma | | noTaint | boolean | No | Exclude nodes with any taints (default: false) | | sortBy | string | No | Sort by: cpu.util, mem.util, cpu.request, mem.request, cpu.limit, mem.limit, cpu.util.percentage, mem.util.percentage, name | | format | string | No | Output format: table, json, yaml (default: table) |

Examples:

// Basic node overview
{
  "cluster": "c-abc123"
}

// Include pods detail
{
  "cluster": "c-abc123",
  "pods": true
}

// Include utilization metrics (requires metrics-server)
{
  "cluster": "c-abc123",
  "util": true
}

// Full detail with utilization
{
  "cluster": "c-abc123",
  "pods": true,
  "util": true
}

// Filter by namespace
{
  "cluster": "c-abc123",
  "namespace": "production"
}

// Sort by CPU utilization
{
  "cluster": "c-abc123",
  "sortBy": "cpu.util"
}

// Filter by node labels (show only worker nodes)
{
  "cluster": "c-abc123",
  "nodeLabelSelector": "node-role.kubernetes.io/worker=true"
}

// Include container-level details
{
  "cluster": "c-abc123",
  "containers": true
}

// Show pod counts per node
{
  "cluster": "c-abc123",
  "podCount": true
}

// Show node labels in output
{
  "cluster": "c-abc123",
  "showLabels": true
}

// Hide request columns (show only limits)
{
  "cluster": "c-abc123",
  "hideRequests": true
}

// Filter by namespace labels
{
  "cluster": "c-abc123",
  "namespaceLabelSelector": "env=production"
}

// Filter by node taints (include nodes with specific taint)
{
  "cluster": "c-abc123",
  "nodeTaints": "dedicated=special:NoSchedule"
}

// Exclude nodes with specific taint
{
  "cluster": "c-abc123",
  "nodeTaints": "dedicated=special:NoSchedule-"
}

// Exclude all tainted nodes
{
  "cluster": "c-abc123",
  "noTaint": true
}

// Sort by CPU utilization percentage
{
  "cluster": "c-abc123",
  "sortBy": "cpu.util.percentage"
}

Show all dependencies or dependents of any Kubernetes resource as a tree. Covers OwnerReference chains, Pod→Node/SA/ConfigMap/Secret/PVC, Service→Pod (label selector), Ingress→IngressClass/Service/TLS Secret, PVC↔PV→StorageClass, RBAC bindings, PDB→Pod, and Events.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind (e.g., deployment, pod, service, ingress, node) | | namespace | string | No | Namespace (optional for cluster-scoped resources) | | name | string | Yes | Resource name | | direction | string | No | Traversal direction: dependents (default) or dependencies | | depth | integer | No | Maximum traversal depth, 1-20 (default: 10) | | format | string | No | Output format: tree, json (default: tree) |

Get a Kubernetes resource by kind, namespace, and name.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind (e.g., pod, deployment, service) | | namespace | string | No | Namespace (optional for cluster-scoped resources) | | name | string | Yes | Resource name | | format | string | No | Output format: json, yaml (default: json) | | showSensitiveData | boolean | No | Show sensitive data values (e.g., Secret data). Default: false. Only takes effect when global --show-sensitive-data is enabled. When global setting is disabled, data is always masked with *** |

List Kubernetes resources by kind.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind | | namespace | string | No | Namespace (empty = all namespaces) | | name | string | No | Filter by name (partial match) | | labelSelector | string | No | Label selector (e.g., "app=nginx,env=prod") | | limit | integer | No | Items per page (default: 100) | | page | integer | No | Page number, starting from 1 (default: 1) | | format | string | No | Output format: json, table, yaml (default: json) | | showSensitiveData | boolean | No | Show sensitive data values (e.g., Secret data). Default: false. Only takes effect when global --show-sensitive-data is enabled. When global setting is disabled, data is always masked with *** |

Get logs from a pod container. Supports multi-pod log aggregation via label selector with time-based sorting.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | namespace | string | Yes | Namespace | | name | string | No | Pod name (required if labelSelector not specified) | | labelSelector | string | No | Label selector for multi-pod log aggregation (e.g., "app=nginx") | | container | string | No | Container name (empty = all containers) | | tailLines | integer | No | Lines from end (default: 100) | | sinceSeconds | integer | No | Logs from last N seconds | | timestamps | boolean | No | Include timestamps (default: true) | | previous | boolean | No | Previous container instance (default: false) | | keyword | string | No | Filter log lines containing this keyword (case-insensitive) |

Notes:

• When labelSelector is specified, logs from all matching pods are aggregated and sorted by timestamp
• Output format for single pod: [container] timestamp content
• Output format for multi-pod: [pod/container] timestamp content

Get pod diagnostics: details, parent workload, metrics, and logs.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | namespace | string | Yes | Namespace | | name | string | Yes | Pod name |

View rollout history for Deployments. Shows revision history with change annotations (similar to kubectl rollout history).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | namespace | string | Yes | Namespace | | name | string | Yes | Deployment name |

Analyze node health and resource usage. Shows node capacity, allocatable resources, pod distribution, and identifies potential issues.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | name | string | No | Node name (if empty, analyzes all nodes) |

Describe a Kubernetes resource with its related events. Similar to kubectl describe.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind (e.g., pod, deployment, service, node) | | namespace | string | No | Namespace (optional for cluster-scoped resources) | | name | string | Yes | Resource name | | format | string | No | Output format: json, yaml (default: json) | | showSensitiveData | boolean | No | Show sensitive data values (e.g., Secret data). Default: false. Only takes effect when global --show-sensitive-data is enabled. When global setting is disabled, data is always masked with *** |

Compare two Kubernetes resource versions and show the differences as a git-style diff. Useful for comparing current vs desired state, or before/after changes.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | resource1 | string | Yes | First resource version as JSON string (the 'before' or 'old' version). Use kubernetes_get to retrieve the resource. | | resource2 | string | Yes | Second resource version as JSON string (the 'after' or 'new' version). Use kubernetes_get to retrieve the resource. | | ignoreStatus | boolean | No | Ignore changes under the status field when computing diffs (default: false) | | ignoreMeta | boolean | No | Ignore non-essential metadata differences like managedFields, resourceVersion, etc. (default: false) |

Examples:

// Compare two versions of the same deployment
// First, get the current resource
{
  "cluster": "c-abc123",
  "kind": "deployment",
  "namespace": "default",
  "name": "nginx"
}
// Then compare with previous version (from rollout history)
{
  "resource1": "<previous-revision-json>",
  "resource2": "<current-revision-json>",
  "ignoreMeta": true
}

Get really all Kubernetes resources in the cluster (inspired by ketall). Unlike kubectl get all, this shows all resource types including ConfigMaps, Secrets, RBAC resources, CRDs, and other resources that are normally hidden.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | namespace | string | No | Filter by namespace (optional, empty for all namespaces) | | name | string | No | Filter by resource name (partial match, client-side) | | labelSelector | string | No | Label selector for filtering (e.g., "app=nginx,env=prod") | | excludeEvents | boolean | No | Exclude events from output (default: true, as events are often noisy) | | scope | string | No | Filter by scope: 'namespaced' for namespaced resources only, 'cluster' for cluster-scoped resources only, or empty for all | | since | string | No | Only show resources created since this duration (e.g., '1h30m', '2d', '1w') | | limit | integer | No | Limit number of resources per API call (0 for no limit, default: 0) | | format | string | No | Output format: json, table, yaml (default: table) |

Examples:

// Get all resources in the cluster
{
  "cluster": "c-abc123"
}

// Get all resources in a specific namespace
{
  "cluster": "c-abc123",
  "namespace": "production"
}

// Get only cluster-scoped resources
{
  "cluster": "c-abc123",
  "scope": "cluster"
}

// Get resources created in the last 24 hours
{
  "cluster": "c-abc123",
  "since": "24h"
}

// Get all resources with specific labels
{
  "cluster": "c-abc123",
  "labelSelector": "app=nginx,env=prod"
}

Watch Kubernetes resources and return git-style diffs of changes at regular intervals, similar to the Linux watch command.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind (e.g., pod, deployment, service, or dotted resource.group form) | | namespace | string | No | Namespace (empty = all namespaces or cluster-scoped resources) | | labelSelector | string | No | Label selector (e.g., "app=nginx,env=prod") | | fieldSelector | string | No | Field selector for filtering resources | | ignoreStatus | boolean | No | Ignore changes under the status field when computing diffs (similar to --no-status) | | ignoreMeta | boolean | No | Ignore non-essential metadata differences (similar to --no-meta) | | intervalSeconds | integer | No | Interval in seconds between evaluations (default: 10, min: 1, max: 600) | | iterations | integer | No | Number of times to re-evaluate and diff before returning (default: 6, min: 1, max: 100) |

Notes:

• Each iteration compares the current resource state with the previous iteration and only emits diffs when there are changes.
• The tool returns the concatenated diffs for all iterations in a single response.

Examples:

// Watch pods in a namespace for changes
{
  "cluster": "c-abc123",
  "kind": "pod",
  "namespace": "production",
  "intervalSeconds": 5,
  "iterations": 3
}

// Watch deployments and ignore status changes
{
  "cluster": "c-abc123",
  "kind": "deployment",
  "namespace": "default",
  "ignoreStatus": true,
  "intervalSeconds": 10,
  "iterations": 6
}

// Watch resources by label selector
{
  "cluster": "c-abc123",
  "kind": "pod",
  "labelSelector": "app=nginx",
  "intervalSeconds": 5,
  "iterations": 12
}

List Kubernetes events. Supports filtering by namespace, involved object name, and kind.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | namespace | string | No | Namespace (empty = all namespaces) | | name | string | No | Filter by involved object name | | kind | string | No | Filter by involved object kind (e.g., Pod, Deployment, Node) | | limit | integer | No | Events per page (default: 50) | | page | integer | No | Page number, starting from 1 (default: 1) | | format | string | No | Output format: json, table, yaml (default: table) |

Create a Kubernetes resource. Disabled when read_only=true.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | resource | string | Yes | JSON manifest (must include apiVersion, kind, metadata, spec) |

Patch a resource using JSON Patch (RFC 6902). Disabled when read_only=true.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind | | namespace | string | No | Namespace (optional for cluster-scoped) | | name | string | Yes | Resource name | | patch | string | Yes | JSON Patch array, e.g., [{"op":"replace","path":"/spec/replicas","value":3}] |

Delete a Kubernetes resource. Disabled when read_only=true or disable_destructive=true.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | Yes | Cluster ID | | kind | string | Yes | Resource kind | | namespace | string | No | Namespace (optional for cluster-scoped) | | name | string | Yes | Resource name |

rancher

List available Rancher clusters.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No | Filter by cluster name (partial match) | | limit | integer | No | Items per page (default: 100) | | page | integer | No | Page number (default: 1) | | format | string | No | Output format: json, table, yaml (default: json) |

List Rancher projects.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | cluster | string | No | Filter by cluster ID | | name | string | No | Filter by project name (partial match) | | limit | integer | No | Items per page (default: 100) | | page | integer | No | Page number (default: 1) | | format | string | No | Output format: json, table, yaml (default: json) |

Development

Build

make build

Run with mcp-inspector

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

See DEVELOPMENT.md for more details.

Contributing

See CONTRIBUTING.md for guidelines.

Support

• GitHub Issues
• Troubleshooting Guide

License

Apache-2.0