rancher-mcp-server

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)
  • Inspect pods with parent workload, metrics, and logs
• 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
  • Secret data is never exposed, only metadata
• 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

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

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

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

Toolsets

kubernetes

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