rancher-mcp-server

Model Context Protocol (MCP) server for the Rancher ecosystem: multi-cluster Kubernetes, Harvester HCI (VMs, storage, networks), and Fleet GitOps.

Demo

A walkthrough of how this MCP server works (example in Cursor).

https://github.com/user-attachments/assets/7d8fb814-e504-47b4-956d-28f43aeea3b8

Features

• Harvester toolset: List/get VMs, images, volumes, networks, hosts; VM actions; addon list/switch (enable/disable)
• Rancher toolset: Clusters and projects via Steve (management proxy); Norman management API (`/v3`) for schemas, users, tokens, auth configs, global role bindings, cluster registration tokens, node drivers, cloud credentials, catalogs, cluster repos, feature flags, settings, audit (when exposed); support bundle and generic actions when writes are enabled
• Kubernetes toolset: List/get/create/patch/delete resources by apiVersion/kind; describe (resource + events), events, capacity
• Helm toolset: List/get/history of releases; install, upgrade, rollback, uninstall; repo list
• Fleet toolset: GitRepo list/get/create; Bundle list; Fleet cluster list; drift detection
• Rancher APIs: Same Bearer token for Steve (`/k8s/clusters/...`) and Norman (`/v3/...`); no CLI wrappers
• Security: Read-only default, disable-destructive, sensitive data masking (Norman token/credential fields redacted unless `--show-sensitive-data`)
• Config: Flags, env (`RANCHER_MCP_*`), or file (YAML/TOML)

Quick start

Install

npm install -g rancher-mcp-server

Cursor

Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

{
  "mcpServers": {
    "rancher": {
      "command": "npx",
      "args": [
        "-y", "rancher-mcp-server",
        "--rancher-server-url", "https://rancher.example.com",
        "--rancher-token", "token-xxxxx:yyyy",
        "--toolsets", "harvester,rancher,kubernetes,fleet"
      ]
    }
  }
}

Restart Cursor after saving. Check Settings → Tools & MCP that rancher is listed and enabled.

Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

{
  "mcpServers": {
    "rancher": {
      "command": "npx",
      "args": [
        "-y", "rancher-mcp-server",
        "--rancher-server-url", "https://rancher.example.com",
        "--rancher-token", "token-xxxxx:yyyy",
        "--toolsets", "harvester,rancher,kubernetes,fleet"
      ]
    }
  }
}

With env vars instead of args

If you prefer to keep the token out of the JSON config:

{
  "mcpServers": {
    "rancher": {
      "command": "npx",
      "args": ["-y", "rancher-mcp-server"],
      "env": {
        "RANCHER_MCP_RANCHER_SERVER_URL": "https://rancher.example.com",
        "RANCHER_MCP_RANCHER_TOKEN": "token-xxxxx:yyyy",
        "RANCHER_MCP_TOOLSETS": "harvester,rancher,kubernetes"
      }
    }
  }
}

Enable write operations

For VM create, snapshots, backups, image/volume create, addon switch, host maintenance mode, VPC create/update/delete, Kubernetes create/patch/delete, Helm install/upgrade/rollback, Fleet gitrepo create/delete, and Norman writes (tokens, users, auth configs, role bindings, cluster registration tokens, cloud credentials, catalog refresh, feature flags, settings, `rancher_norman_action`, support bundle), add `--read-only=false`. Delete operations (Norman tokens/bindings/registration tokens/cloud credentials, plus existing toolset deletes) also require `--disable-destructive=false` (default).

{
  "mcpServers": {
    "rancher": {
      "command": "npx",
      "args": [
        "-y", "rancher-mcp-server",
        "--rancher-server-url", "https://rancher.example.com",
        "--rancher-token", "token-xxxxx:yyyy",
        "--toolsets", "harvester,rancher,kubernetes,helm,fleet",
        "--read-only=false"
      ]
    }
  }
}

Streamable HTTP transport

For web clients or remote access (e.g. Claude Code `claude mcp add -t http`), add `--transport` and `--port`:

{
  "mcpServers": {
    "rancher": {
      "command": "npx",
      "args": [
        "-y", "rancher-mcp-server",
        "--rancher-server-url", "https://rancher.example.com",
        "--rancher-token", "token-xxxxx:yyyy",
        "--transport", "http",
        "--port", "8080"
      ]
    }
  }
}

The server uses the MCP Streamable HTTP transport. The default MCP path is `/mcp`; connect to `http://localhost:8080/mcp` (or your server base URL + `/mcp`). Best supported with Claude Code; Cursor support may vary.

Build from source

If you prefer to build the Go binary yourself:

go build -o rancher-mcp-server ./cmd/rancher-mcp-server

Then reference the binary directly in your MCP config:

{
  "mcpServers": {
    "rancher": {
      "command": "/absolute/path/to/rancher-mcp-server",
      "args": [
        "--rancher-server-url", "https://rancher.example.com",
        "--rancher-token", "token-xxxxx:yyyy",
        "--toolsets", "harvester,rancher,kubernetes,fleet"
      ]
    }
  }
}

Configuration

Harvester tools

List tools accept `cluster` (required), `namespace`, `format` (json|table), `limit` (default 100), `continue` (pagination token for next page). Write tools require `read_only: false`.

Creating a VM on KubeOVN VPC with external internet

Use `harvester_vm_create` with:

1. network: Name of the overlay network (NAD) linked to a KubeOVN subnet. Create via `harvester_network_create` (type=kubeovn) then `harvester_subnet_create` with `provider={network}.{namespace}.ovn`, `vpc=`, and `nat_outgoing=true`.

2. interface_type: `managedtap` (recommended for KubeOVN) or `bridge`. Uses Multus as primary network.

3. subnet: Optional KubeOVN subnet name for `ovn.kubernetes.io/logical_switch` annotation.

Example: VM on network `vswitch1` in namespace `default`, managedTap interface, subnet `vswitch1-subnet`:

harvester_vm_create cluster= namespace=default name=testvm image= network=vswitch1 interface_type=managedtap subnet=vswitch1-subnet

Rancher tools

Rancher tools use the management cluster (`local`). There is no `cluster` parameter on these tools.

Steve API (management resources)

Norman API (`https:///v3/...`)

Norman tools call Rancher’s JSON management API. Discover types and collection URLs for your server with `rancher_norman_schema_list` / `rancher_norman_schema_get` (schema ids such as `user`, `token`, `cluster`).

Read-only (always registered with the `rancher` toolset)

When `--read-only=false`

When `--read-only=false` and `--disable-destructive=false`

Norman responses: catalog, cluster repos, audit

• `rancher_cluster_repo_list` / `rancher_cluster_repo_get`: Tries Norman `/v3/clusterrepos` first. If that returns 404 (common), falls back to `catalog.cattle.io/v1` `ClusterRepo` on the local cluster via Steve/Kubernetes, trying namespaces `cattle-global-data`, `fleet-default`, `fleet-local`, `cattle-fleet-system`. Success JSON includes `"_source":"kubernetes_api_fallback"`. If nothing works, the tool still returns 200-style JSON with `"_source":"unavailable"` and per-attempt errors—not a hard MCP error—so automation can continue.
• `rancher_catalog_list` / `rancher_catalog_get`: If Norman `/v3/catalogs` is not registered (404), returns JSON with `"_source":"unavailable"` instead of failing.
• `rancher_audit_log_list`: If the server returns 404 or 405 (GET not supported), returns JSON with `"_source":"unavailable"` and `_http_status`; audit may be disabled or exposed outside Norman.

For catalog data when ClusterRepo is unavailable everywhere, use `kubernetes_list` on cluster `local` with `api_version` `catalog.cattle.io/v1` and `kind` `ClusterRepo`, or Helm / Fleet tools as appropriate.

Helm tools

All tools take `cluster` (Rancher cluster ID). Install/upgrade require `chart`, `release`; optional `repo_url`, `version`, `values` (JSON).

Fleet tools

All tools use the Rancher management cluster (`local`). Optional `namespace` (default: fleet-default). List tools support `format`, `limit`, `continue` (pagination). `fleet_gitrepo_create` requires `name`, `repo`; optional `branch`, `paths`. `fleet_gitrepo_action` supports: pause, unpause, disablePolling, enablePolling, forceUpdate. `fleet_gitrepo_clone` copies spec from an existing GitRepo to a new name.

Kubernetes tools

All tools take `cluster` (Rancher cluster ID). List/get support `namespace`, `format` (json|table), `limit`, `continue` (pagination). Create/patch/delete are gated by `read_only` and `disable_destructive`. `kubernetes_logs` does not support follow (streaming); use `tail_lines` and `since_seconds` to limit output. In some Rancher/proxy setups pod logs can return 503 or stream errors; see Troubleshooting.

Setup: Rancher token & Harvester cluster ID

Get a Rancher API token

1. Log in to your Rancher UI.

2. Click your profile/avatar (top right) → Account & API Keys (or API & Keys).

3. Click Create API Key, name it (e.g. `mcp-server`), then Create.

4. Copy the token once (format like `token-abc12:xyz...`). Use it as `--rancher-token` or `RANCHER_MCP_RANCHER_TOKEN`.

Find your Harvester cluster ID

Harvester tools require the cluster ID (e.g. `c-tx8rn`) on each call.

• From Rancher UI: Go to Cluster Management → open your Harvester cluster. The URL contains the cluster ID: `.../c//...`.
• From API (Steve): `curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_RANCHER_URL/k8s/clusters/local/v1/management.cattle.io.clusters" | jq '.data[] | {name: .metadata.name}'`
• Norman schemas: `curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_RANCHER_URL/v3/schemas" | jq '.data[0:5].id'`

Docker (Streamable HTTP)

For HTTP server mode, use the container image from GitHub Container Registry (ghcr.io). For Cursor/Claude with stdio, use npm (see Quick start).

Run the server and expose the port:

docker run -d -p 8080:8080 \
  -e RANCHER_MCP_RANCHER_SERVER_URL=https://rancher.example.com \
  -e RANCHER_MCP_RANCHER_TOKEN="token-xxxxx:yyyy" \
  -e RANCHER_MCP_TRANSPORT=http \
  -e RANCHER_MCP_PORT=8080 \
  ghcr.io/mrostamii/rancher-mcp-server:latest

Connect clients to the MCP endpoint: `http://localhost:8080/mcp` (Streamable HTTP; default path is `/mcp`). Example: `claude mcp add -t http rancher http://localhost:8080/mcp`

Supported platforms

• macOS (Apple Silicon & Intel)
• Linux (x64 & ARM64)
• Windows (x64)

Troubleshooting

License

Apache-2.0