Rancher MCP Server

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

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

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

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

{ "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. CheckSettings → Tools & MCPthatrancheris listed and enabled.

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

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

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, andNormanwrites (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.Deleteoperations (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" ] } } }

For web clients or remote access (e.g. Claude Codeclaude mcp add -t http), add--transportand--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 tohttp://localhost:8080/mcp(or your server base URL +/mcp). Best supported with Claude Code; Cursor support may vary.

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

List tools acceptcluster(required),namespace,format(json|table),limit(default 100),continue(pagination token for next page). Write tools requireread_only: false.

Creating a VM on KubeOVN VPC with external internet

Example: VM on networkvswitch1in namespacedefault, managedTap interface, subnetvswitch1-subnet:

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

Rancher tools use themanagement cluster(local). There is noclusterparameter on these tools.

Norman API (https://<rancher>/v3/...)

Norman tools call Rancher’s JSON management API. Discover types and collection URLs foryourserver withrancher_norman_schema_list/rancher_norman_schema_get(schema ids such asuser,token,cluster).

Read-only (always registered with theranchertoolset)

When--read-only=falseand--disable-destructive=false

Norman responses: catalog, cluster repos, audit

- rancher_cluster_repo_list/rancher_cluster_repo_get: Tries Norman/v3/clusterreposfirst. If that returns404(common), falls back tocatalog.cattle.io/v1ClusterRepoon thelocalcluster via Steve/Kubernetes, trying namespacescattle-global-data,fleet-default,fleet-local,cattle-fleet-system. Success JSON includes"_source":"kubernetes_api_fallback". If nothing works, the tool still returns200-style JSONwith"_source":"unavailable"and per-attempt errors—not a hard MCP error—so automation can continue.
- rancher_catalog_list/rancher_catalog_get: If Norman/v3/catalogsis not registered (404), returns JSON with"_source":"unavailable"instead of failing.
- rancher_audit_log_list: If the server returns404or405(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, usekubernetes_liston clusterlocalwithapi_versioncatalog.cattle.io/v1andkindClusterRepo, orHelm/Fleettools as appropriate.

All tools takecluster(Rancher cluster ID). Install/upgrade requirechart,release; optionalrepo_url,version,values(JSON).

All tools use the Rancher management cluster (local). Optionalnamespace(default: fleet-default). List tools supportformat,limit,continue(pagination).fleet_gitrepo_createrequiresname,repo; optionalbranch,paths.fleet_gitrepo_actionsupports: pause, unpause, disablePolling, enablePolling, forceUpdate.fleet_gitrepo_clonecopies spec from an existing GitRepo to a new name.

All tools takecluster(Rancher cluster ID). List/get supportnamespace,format(json|table),limit,continue(pagination). Create/patch/delete are gated byread_onlyanddisable_destructive.kubernetes_logsdoes not support follow (streaming); usetail_linesandsince_secondsto limit output. In some Rancher/proxy setups pod logs can return 503 or stream errors; see Troubleshooting.

Setup: Rancher token & Harvester cluster ID

Harvester tools require thecluster 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/<cluster-id>/....
- 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'

ForHTTP server mode, use the container image fromGitHub Container Registry(ghcr.io). For Cursor/Claude with stdio, usenpm(see Quick start).

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

Provides safe, read-only access to Kubernetes cluster resources for debugging and inspection.