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
  • 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
• 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

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

# High-risk container operations are disabled by default.
# enable_container_exec 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

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
RANCHER_MCP_ENABLE_CONTAINER_EXEC=false

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.

High-Risk Container Operations

Container exec and file mutation tools are disabled by default. To expose kubernetes_exec, administrators must set read_only: false and enable enable_container_exec. The tool accepts only an argv-style command array and does not support stdin or TTY sessions.

{
  "cluster": "c-abc123",
  "namespace": "default",
  "name": "api-7f8d8",
  "container": "api",
  "command": ["printenv", "HOSTNAME"]
}

The response is JSON with exitCode, stdout, and stderr. A non-zero command exit is returned as a structured result; validation and transport failures are returned as tool errors.

Toolsets

kubernetes

// 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"
}

{
  "cluster": "c-abc123",
  "apiVersion": "catalog.cattle.io/v1",
  "kind": "App",
  "namespace": "cattle-system"
}

// 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 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 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
}

rancher

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