Rancher MCP Server

Servidor do Protocolo de Contexto de Modelo (MCP) para o ecossistema Rancher: Kubernetes multi-cluster, Harvester HCI (VMs, armazenamento, redes) e Fleet GitOps.

GitHub

Experimente este MCPPatrocinado

Documentação

rancher-mcp-server

Servidor Model Context Protocol (MCP) para o ecossistema Rancher: Kubernetes multi-cluster, Harvester HCI (VMs, armazenamento, redes) e Fleet GitOps.

Demonstração

Um passo a passo de como este servidor MCP funciona (exemplo no Cursor).

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

Recursos

Conjunto de ferramentas Harvester: Listar/obter VMs, imagens, volumes, redes, hosts; ações de VM; listar/alternar addons (ativar/desativar)
Conjunto de ferramentas Rancher: Clusters e projetos via Steve (proxy de gerenciamento); API de gerenciamento Norman (/v3) para esquemas, usuários, tokens, configurações de autenticação, vínculos de função globais, tokens de registro de cluster, drivers de nó, credenciais de nuvem, catálogos, repositórios de cluster, flags de recurso, configurações, auditoria (quando exposta); pacote de suporte e ações genéricas quando gravações estão habilitadas
Conjunto de ferramentas Kubernetes: Listar/obter/criar/atualizar/excluir recursos por apiVersion/kind; descrever (recurso + eventos), eventos, capacidade
Conjunto de ferramentas Helm: Listar/obter/histórico de releases; instalar, atualizar, fazer rollback, desinstalar; lista de repositórios
Conjunto de ferramentas Fleet: Listar/obter/criar GitRepo; listar Bundle; listar clusters Fleet; detecção de drift
APIs Rancher: Mesmo token Bearer para Steve (/k8s/clusters/...) e Norman (/v3/...); sem wrappers de CLI
Segurança: Somente leitura por padrão, desabilitar operações destrutivas, mascaramento de dados sensíveis (campos de token/credenciais Norman redigidos, exceto quando --show-sensitive-data)
Configuração: Flags, env (RANCHER_MCP_*) ou arquivo (YAML/TOML)

Início rápido

Instalação

npm install -g rancher-mcp-server

Cursor

Adicione a .cursor/mcp.json (nível do projeto) ou ~/.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"
      ]
    }
  }
}

Reinicie o Cursor após salvar. Verifique em Configurações → Ferramentas e MCP se rancher está listado e habilitado.

Claude Desktop

Adicione à configuração do seu Claude Desktop (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"
      ]
    }
  }
}

Com variáveis de ambiente em vez de argumentos

Se preferir manter o token fora da configuração JSON:

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

Habilitar operações de gravação

Para criação de VM, snapshots, backups, criação de imagem/volume, alternância de addon, modo de manutenção de host, criação/atualização/exclusão de VPC, criação/atualização/exclusão de Kubernetes, instalação/atualização/rollback de Helm, criação/exclusão de gitrepo Fleet e gravações Norman (tokens, usuários, configurações de autenticação, vínculos de função, tokens de registro de cluster, credenciais de nuvem, atualização de catálogo, flags de recurso, configurações, rancher_norman_action, pacote de suporte), adicione --read-only=false. As operações Excluir (tokens/bindings/tokens de registro/credenciais de nuvem Norman, além das exclusões existentes do conjunto de ferramentas) também exigem --disable-destructive=false (padrão).

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

Transporte HTTP Streamable

Para clientes web ou acesso remoto (ex.: Claude Code claude mcp add -t http), adicione --transport e --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"
      ]
    }
  }
}

O servidor usa o transporte MCP Streamable HTTP. O caminho MCP padrão é /mcp; conecte-se a http://localhost:8080/mcp (ou à URL base do seu servidor + /mcp). Melhor suporte com Claude Code; o suporte ao Cursor pode variar.

Compilar a partir do código-fonte

Se preferir compilar o binário Go você mesmo:

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

Então referencie o binário diretamente na sua configuração MCP:

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

Configuração

Opção	Env	Padrão	Descrição
`--rancher-server-url`	`RANCHER_MCP_RANCHER_SERVER_URL`	—	URL do servidor Rancher (obrigatório)
`--rancher-token`	`RANCHER_MCP_RANCHER_TOKEN`	—	Token Bearer (obrigatório)
`--tls-insecure`	`RANCHER_MCP_TLS_INSECURE`	false	Pular verificação TLS
`--read-only`	`RANCHER_MCP_READ_ONLY`	true	Desabilitar operações de gravação
`--disable-destructive`	`RANCHER_MCP_DISABLE_DESTRUCTIVE`	false	Desabilitar operações de exclusão
`--show-sensitive-data`	`RANCHER_MCP_SHOW_SENSITIVE_DATA`	false	Mostrar campos de token/credenciais Norman sem redação (usar com cuidado)
`--toolsets`	`RANCHER_MCP_TOOLSETS`	harvester	Conjuntos de ferramentas a habilitar: harvester, rancher, kubernetes, helm, fleet
`--transport`	`RANCHER_MCP_TRANSPORT`	stdio	Transporte: stdio ou http (HTTP Streamable; caminho padrão `/mcp`)
`--port`	`RANCHER_MCP_PORT`	0	Porta para HTTP (0 = somente stdio)

Ferramentas Harvester

Ferramenta	Descrição
`harvester_vm_list`	Listar VMs com status, namespace, spec/status
`harvester_vm_get`	Obter uma VM (spec e status completos)
`harvester_vm_action`	iniciar, parar, reiniciar, pausar, retomar, migrar
`harvester_vm_create`	Criar VM (quando não estiver somente leitura). Suporta rede, interface_type (managedtap/bridge/masquerade), subnet para VPC KubeOVN.
`harvester_vm_snapshot`	Criar/listar/restaurar/excluir snapshots de VM
`harvester_vm_backup`	Criar/listar/restaurar backups de VM (Destino de Backup)
`harvester_image_list`	Listar imagens de VM (VirtualMachineImage)
`harvester_image_create`	Criar imagem de VM a partir de URL (quando não estiver somente leitura)
`harvester_volume_list`	Listar PVCs (volumes suportados por Longhorn)
`harvester_volume_create`	Criar volume/PVC (opcionalmente a partir de imagem)
`harvester_network_list`	Listar redes de VM (NetworkAttachmentDefinition)
`harvester_network_create`	Criar rede de VM - overlay KubeOVN ou VLAN (quando não estiver somente leitura)
`harvester_network_update`	Atualizar configuração de rede de VM (quando não estiver somente leitura)
`harvester_network_delete`	Excluir rede de VM (quando ações destrutivas forem permitidas)
`harvester_subnet_list`	Listar Subnets KubeOVN (requer kubeovn-operator)
`harvester_subnet_create`	Criar Subnet em VPC para rede de VM (quando não estiver somente leitura)
`harvester_subnet_update`	Atualizar namespaces/NAT do Subnet (quando não estiver somente leitura)
`harvester_subnet_delete`	Excluir Subnet (quando ações destrutivas forem permitidas)
`harvester_host_list`	Listar nós (hosts Harvester)
`harvester_host_action`	Ativar/desativar modo de manutenção em um host (cordon/uncordon)
`harvester_settings`	Listar ou obter configurações do cluster Harvester (backup-target, etc.)
`harvester_addon_list`	Listar addons Harvester (estado habilitado/desabilitado)
`harvester_addon_switch`	Habilitar ou desabilitar um addon (quando não estiver somente leitura)
`harvester_vpc_list`	Listar VPCs KubeOVN (requer addon kubeovn-operator)
`harvester_vpc_create`	Criar uma VPC KubeOVN (quando não estiver somente leitura)
`harvester_vpc_update`	Atualizar namespaces de uma VPC KubeOVN (quando não estiver somente leitura)
`harvester_vpc_delete`	Excluir uma VPC KubeOVN (quando ações destrutivas forem permitidas)

As ferramentas de listagem aceitam cluster (obrigatório), namespace, format (json|table), limit (padrão 100), continue (token de paginação para a próxima página). As ferramentas de gravação exigem read_only: false.

Criando uma VM na VPC KubeOVN com internet externa

Use harvester_vm_create com:

network: Nome da rede overlay (NAD) vinculada a uma subnet KubeOVN. Crie via harvester_network_create (type=kubeovn) e depois harvester_subnet_create com provider={network}.{namespace}.ovn, vpc=<vpc-name> e nat_outgoing=true.
interface_type: managedtap (recomendado para KubeOVN) ou bridge. Usa Multus como rede primária.
subnet: Nome opcional da subnet KubeOVN para anotação ovn.kubernetes.io/logical_switch.

Exemplo: VM na rede vswitch1 no namespace default, interface managedTap, subnet vswitch1-subnet:

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

Ferramentas Rancher

As ferramentas Rancher usam o cluster de gerenciamento (local). Não há parâmetro cluster nessas ferramentas.

API Steve (recursos de gerenciamento)

Ferramenta	Descrição
`rancher_cluster_list`	Listar clusters Rancher (gerenciamento)
`rancher_cluster_get`	Obter um cluster (saúde, versão, contagem de nós)
`rancher_project_list`	Listar projetos Rancher
`rancher_overview`	Visão geral: contagem de clusters e contagem de projetos

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

As ferramentas Norman chamam a API de gerenciamento JSON do Rancher. Descubra tipos e URLs de coleção para seu servidor com rancher_norman_schema_list / rancher_norman_schema_get (ids de esquema como user, token, cluster).

Somente leitura (sempre registradas com o conjunto de ferramentas rancher)

Ferramenta	Descrição
`rancher_norman_schema_list`	Listar esquemas de API (`/v3/schemas`)
`rancher_norman_schema_get`	Obter um esquema por id
`rancher_user_list` / `rancher_user_get`	Usuários
`rancher_auth_config_list` / `rancher_auth_config_get`	Provedores de autenticação (local, OIDC, etc.)
`rancher_token_list` / `rancher_token_get`	Tokens de API (valores redigidos, exceto quando `--show-sensitive-data`)
`rancher_global_role_binding_list` / `rancher_global_role_binding_get`	Vínculos de função globais
`rancher_cluster_registration_token_list` / `rancher_cluster_registration_token_get`	Tokens de registro de cluster
`rancher_node_driver_list`	Drivers de nó
`rancher_cloud_credential_list` / `rancher_cloud_credential_get`	Credenciais de nuvem (segredos redigidos, exceto quando `--show-sensitive-data`)
`rancher_catalog_list` / `rancher_catalog_get`	Catálogos Norman legados (`/v3/catalogs`)
`rancher_cluster_repo_list` / `rancher_cluster_repo_get`	Repositórios de cluster do catálogo de aplicativos (veja nota abaixo)
`rancher_feature_flag_list` / `rancher_feature_flag_get`	Flags de recurso (`/v3/features`)
`rancher_setting_list` / `rancher_setting_get`	Configurações globais (`/v3/settings`)
`rancher_audit_log_list`	`GET /v3/auditlogs` quando suportado (geralmente 404/405; veja nota abaixo)

Quando --read-only=false

Ferramenta	Descrição
`rancher_norman_action`	`POST` um `?action=` Norman em um caminho de recurso sob `/v3`
`rancher_token_create`	Criar token de API
`rancher_auth_config_update`	Substituir uma configuração de autenticação (`PUT`)
`rancher_user_create`	Criar usuário
`rancher_user_disable` / `rancher_user_enable`	Ações de habilitar/desabilitar usuário
`rancher_global_role_binding_create`	Criar vínculo de função global
`rancher_cluster_registration_token_create`	Criar token de registro
`rancher_cloud_credential_create`	Criar credencial de nuvem
`rancher_catalog_refresh`	Atualizar catálogo legado (`?action=refresh`)
`rancher_feature_flag_set`	Atualizar flag de recurso (`PUT`)
`rancher_setting_update`	Atualizar configuração (`PUT`)
`rancher_supportbundle_generate`	Solicitar pacote de suporte (`generateSupportBundle` em um cluster)

Quando --read-only=false e --disable-destructive=false

Ferramenta	Descrição
`rancher_token_delete`	Excluir token de API
`rancher_global_role_binding_delete`	Excluir vínculo de função global
`rancher_cluster_registration_token_delete`	Excluir token de registro
`rancher_cloud_credential_delete`	Excluir credencial de nuvem

Respostas Norman: catálogo, repositórios de cluster, auditoria

Tradução

rancher_cluster_repo_list / rancher_cluster_repo_get: Tenta Norman /v3/clusterrepos primeiro. Se retornar 404 (comum), recorre a catalog.cattle.io/v1 ClusterRepo no cluster local via Steve/Kubernetes, tentando os namespaces cattle-global-data, fleet-default, fleet-local, cattle-fleet-system. O JSON de sucesso inclui "_source":"kubernetes_api_fallback". Se nada funcionar, a ferramenta ainda retorna JSON estilo 200 com "_source":"unavailable" e erros por tentativa — não um erro MCP grave — para que a automação possa continuar.
rancher_catalog_list / rancher_catalog_get: Se Norman /v3/catalogs não estiver registrado (404), retorna JSON com "_source":"unavailable" em vez de falhar.
rancher_audit_log_list: Se o servidor retornar 404 ou 405 (GET não suportado), retorna JSON com "_source":"unavailable" e _http_status; a auditoria pode estar desabilitada ou exposta fora do Norman.

Para dados de catálogo quando ClusterRepo não estiver disponível em nenhum lugar, use kubernetes_list no cluster local com api_version catalog.cattle.io/v1 e kind ClusterRepo, ou ferramentas Helm / Fleet conforme apropriado.

Ferramentas Helm

Ferramenta	Descrição
`helm_list`	Lista releases do Helm (opcionalmente por namespace, implantadas/com falha/pendentes)
`helm_get`	Obtém detalhes da release (manifesto, valores, notas)
`helm_history`	Obtém histórico de revisões de uma release
`helm_repo_list`	Lista repositórios de charts Helm configurados (da configuração local)
`helm_install`	Instala um chart Helm (quando não é somente leitura)
`helm_upgrade`	Atualiza uma release Helm (quando não é somente leitura)
`helm_rollback`	Reverte uma release para uma revisão anterior (quando não é somente leitura)
`helm_uninstall`	Desinstala uma release (quando ações destrutivas são permitidas)

Todas as ferramentas recebem cluster (ID do cluster Rancher). Instalação/atualização exigem chart, release; opcionais: repo_url, version, values (JSON).

Ferramentas Fleet

Ferramenta	Descrição
`fleet_gitrepo_list`	Lista GitRepos do Fleet (fontes GitOps)
`fleet_gitrepo_get`	Obtém um GitRepo (spec, status)
`fleet_gitrepo_create`	Cria um GitRepo (quando não é somente leitura)
`fleet_gitrepo_delete`	Exclui um GitRepo (quando ações destrutivas são permitidas)
`fleet_gitrepo_action`	Pausa, retoma, desativa polling, ativa polling, forçao atualização
`fleet_gitrepo_clone`	Clona um GitRepo para um novo nome (copia o spec)
`fleet_bundle_list`	Lista Bundles do Fleet (unidades de implantação dos GitRepos)
`fleet_cluster_list`	Lista clusters do Fleet (clusters downstream registrados com o Fleet)
`fleet_drift_detect`	Relata BundleDeployments com estado Modified (drift)

Todas as ferramentas usam o cluster de gerenciamento Rancher (local). Opcional: namespace (padrão: fleet-default). Ferramentas de listagem suportam format, limit, continue (paginação). fleet_gitrepo_create exige name, repo; opcionais: branch, paths. fleet_gitrepo_action suporta: pause, unpause, disablePolling, enablePolling, forceUpdate. fleet_gitrepo_clone copia o spec de um GitRepo existente para um novo nome.

Ferramentas Kubernetes

Ferramenta	Descrição
`kubernetes_list`	Lista recursos por apiVersion/kind (ex.: v1 Pod, apps/v1 Deployment)
`kubernetes_get`	Obtém um recurso por apiVersion, kind, namespace, nome
`kubernetes_describe`	Obtém recurso + eventos recentes
`kubernetes_logs`	Obtém logs recentes de pods (somente tail; container, tailLines, sinceSeconds)
`kubernetes_events`	Lista eventos em um namespace (filtro opcional por involvedObject)
`kubernetes_capacity`	Resumo de capacidade/allocatable por nó
`kubernetes_create`	Cria recurso a partir de JSON (quando não é somente leitura)
`kubernetes_patch`	Aplica patch em recurso com JSON (quando não é somente leitura)
`kubernetes_delete`	Exclui recurso (quando ações destrutivas são permitidas)

Todas as ferramentas recebem cluster (ID do cluster Rancher). Listar/obter suportam namespace, format (json|table), limit, continue (paginação). Criar/aplicar patch/excluir são controlados por read_only e disable_destructive. kubernetes_logs não suporta follow (streaming); use tail_lines e since_seconds para limitar a saída. Em algumas configurações de Rancher/proxy, logs de pods podem retornar 503 ou erros de streaming; consulte Troubleshooting.

Configuração: token Rancher e ID do cluster Harvester

Obter um token de API Rancher

Faça login na interface do Rancher.
Clique no seu perfil/avatar (canto superior direito) → Account & API Keys (ou API & Keys).
Clique em Create API Key, dê um nome (ex.: mcp-server) e depois em Create.
Copie o token uma vez (formato como token-abc12:xyz...). Use-o como --rancher-token ou RANCHER_MCP_RANCHER_TOKEN.

Encontre o ID do seu cluster Harvester

As ferramentas Harvester exigem o ID do cluster (ex.: c-tx8rn) em cada chamada.

Pela interface do Rancher: Vá para Cluster Management → abra seu cluster Harvester. A URL contém o ID do cluster: .../c/<cluster-id>/....
Pela 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}'
Schemas Norman: curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_RANCHER_URL/v3/schemas" | jq '.data[0:5].id'

Docker (Streamable HTTP)

Para modo servidor HTTP, use a imagem de contêiner do GitHub Container Registry (ghcr.io). Para Cursor/Claude com stdio, use npm (veja Quick start).

Execute o servidor e exponha a porta:

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

Conecte clientes ao endpoint MCP: http://localhost:8080/mcp (Streamable HTTP; caminho padrão é /mcp). Exemplo: claude mcp add -t http rancher http://localhost:8080/mcp

Plataformas suportadas

macOS (Apple Silicon e Intel)
Linux (x64 e ARM64)
Windows (x64)

Solução de problemas

Problema	O que verificar
"rancher-server-url and rancher-token are required"	Verifique `--rancher-server-url` e `--rancher-token` nos argumentos, ou as variáveis de ambiente `RANCHER_MCP_RANCHER_SERVER_URL` e `RANCHER_MCP_RANCHER_TOKEN`.
401 Non autorizado	Token expirado ou inválido. Crie uma nova chave de API no Rancher.
Erros de TLS / certificado	Para Rancher com certificado autossinado, passe `--tls-insecure` (somente desenvolvimento).
"cluster not found" ou listas vazias	ID do cluster errado. Obtenha-o da URL da interface ou da API; passe-o como `cluster` para ferramentas Harvester/Kubernetes.
O Cursor não mostra as ferramentas	Reinicie o Cursor após editar `mcp.json`; verifique em Tools & MCP se o servidor está habilitado.
Binário não encontrado	Use caminhos absolutos em `mcp.json` para `command` ao compilar a partir do código-fonte.
`kubernetes_logs` 503 ou erros de streaming	Conhecido em algumas configurações Rancher/proxy (ex.: RKE2). Reduza `tail_lines` ou tente outro cluster; veja rancher/rancher#40711.
Ferramenta Norman retorna `"_source":"unavailable"`	Essa coleção pode não existir na sua versão do Rancher (ex.: `catalogs` legado, `clusterrepos` ou auditoria via `GET`). Use `rancher_norman_schema_list` para ver os tipos registrados, ou `kubernetes_list` / Helm / Fleet para fontes de charts.
A lista de repositórios do cluster mostra `unavailable` ou `data` vazio	`catalog.cattle.io` `ClusterRepo` pode não estar instalado ou ter proxy para seu token; tente `kubernetes_list` com `catalog.cattle.io/v1` e `ClusterRepo` no cluster `local` em todos os namespaces.

Licença

Apache-2.0