Rancher MCP Server

Servidor del Protocolo de Contexto de Modelo (MCP) para el ecosistema Rancher: Kubernetes multi-clúster, Harvester HCI (máquinas virtuales, almacenamiento, redes) y Fleet GitOps.

GitHub

Documentación

rancher-mcp-server

Servidor de Model Context Protocol (MCP) para el ecosistema Rancher: Kubernetes multi-clúster, Harvester HCI (VMs, almacenamiento, redes) y Fleet GitOps.

Demo

Un recorrido de cómo funciona este servidor MCP (ejemplo en Cursor).

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

Características

Conjunto de herramientas Harvester: Listar/obtener VMs, imágenes, volúmenes, redes, hosts; acciones de VM; lista de addons/cambio (habilitar/deshabilitar)
Conjunto de herramientas Rancher: Clústeres y proyectos a través de Steve (proxy de gestión); API de gestión Norman (/v3) para esquemas, usuarios, tokens, configuraciones de autenticación, enlaces de roles globales, tokens de registro de clúster, controladores de nodos, credenciales en la nube, catálogos, repositorios de clúster, indicadores de características, configuraciones, auditoría (cuando está expuesta); paquete de soporte y acciones genéricas cuando las escrituras están habilitadas
Conjunto de herramientas Kubernetes: Listar/obtener/crear/parchear/eliminar recursos por apiVersion/kind; describir (recurso + eventos), eventos, capacidad
Conjunto de herramientas Helm: Listar/obtener/historial de versiones; instalar, actualizar, revertir, desinstalar; lista de repositorios
Conjunto de herramientas Fleet: Listar/obtener/crear GitRepo; lista de Bundles; lista de clústeres Fleet; detección de deriva
APIs de Rancher: Mismo token Bearer para Steve (/k8s/clusters/...) y Norman (/v3/...); sin envoltorios CLI
Seguridad: Solo lectura por defecto, deshabilitar destructivo, enmascaramiento de datos sensibles (campos de token/credenciales de Norman redactados a menos que --show-sensitive-data)
Configuración: Banderas, env (RANCHER_MCP_*) o archivo (YAML/TOML)

Inicio rápido

Instalación

npm install -g rancher-mcp-server

Cursor

Agregar a .cursor/mcp.json (nivel de proyecto) o ~/.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"
      ]
    }
  }
}

Reinicia Cursor después de guardar. Verifica en Configuración → Herramientas y MCP que rancher esté listado y habilitado.

Claude Desktop

Agrega a tu configuración de 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"
      ]
    }
  }
}

Con variables de entorno en lugar de argumentos

Si prefieres mantener el token fuera de la configuración 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 operaciones de escritura

Para creación de VM, instantáneas, copias de seguridad, creación de imagen/volumen, cambio de addon, modo de mantenimiento de host, creación/actualización/eliminación de VPC, creación de gateway NAT de VPC, actualizaciones de configuración de Harvester, creación/parcheo/eliminación de Kubernetes, instalación/actualización/reversión de Helm, creación/eliminación de gitrepo de Fleet, y escrituras Norman (tokens, usuarios, configuraciones de autenticación, enlaces de roles, tokens de registro de clúster, credenciales en la nube, actualización de catálogo, indicadores de características, configuraciones, rancher_norman_action, paquete de soporte), agrega --read-only=false. Las operaciones de eliminación (tokens/bindings/tokens de registro/credenciales en la nube de Norman, eliminación de gateway NAT de VPC, además de las eliminaciones existentes del conjunto de herramientas) también requieren --disable-destructive=false (por defecto).

{
  "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 o acceso remoto (por ejemplo, Claude Code claude mcp add -t http), agrega --transport y --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"
      ]
    }
  }
}

El servidor utiliza el transporte HTTP Streamable de MCP. La ruta MCP predeterminada es /mcp; conéctate a http://localhost:8080/mcp (o la URL base de tu servidor + /mcp). Mejor soportado con Claude Code; el soporte de Cursor puede variar.

Compilar desde el código fuente

Si prefieres compilar el binario Go tú mismo:

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

Luego referencia el binario directamente en tu configuración 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"
      ]
    }
  }
}

Configuración

Opción	Env	Predeterminado	Descripción
`--rancher-server-url`	`RANCHER_MCP_RANCHER_SERVER_URL`	—	URL del servidor Rancher (requerido)
`--rancher-token`	`RANCHER_MCP_RANCHER_TOKEN`	—	Token Bearer (requerido)
`--tls-insecure`	`RANCHER_MCP_TLS_INSECURE`	false	Omitir verificación TLS
`--read-only`	`RANCHER_MCP_READ_ONLY`	true	Deshabilitar operaciones de escritura
`--disable-destructive`	`RANCHER_MCP_DISABLE_DESTRUCTIVE`	false	Deshabilitar operaciones de eliminación
`--show-sensitive-data`	`RANCHER_MCP_SHOW_SENSITIVE_DATA`	false	Mostrar campos de token/credenciales de Norman sin redacción (usar con cuidado)
`--toolsets`	`RANCHER_MCP_TOOLSETS`	harvester	Conjuntos de herramientas a habilitar: harvester, rancher, kubernetes, helm, fleet
`--transport`	`RANCHER_MCP_TRANSPORT`	stdio	Transporte: stdio o http (HTTP Streamable; ruta predeterminada `/mcp`)
`--port`	`RANCHER_MCP_PORT`	0	Puerto para HTTP (0 = solo stdio)

Herramientas de Harvester

Herramienta	Descripción
`harvester_vm_list`	Listar VMs con estado, namespace, spec/status
`harvester_vm_get`	Obtener una VM (spec y estado completos)
`harvester_vm_action`	iniciar, detener, reiniciar, pausar, reanudar, migrar
`harvester_vm_create`	Crear VM (cuando no es solo lectura). Soporta red, interface_type (managedtap/bridge/masquerade), subred para VPC KubeOVN, montajes virtiofs (`virtiofs_service_account`, `virtiofs_secret`, `virtiofs_config_map`) y Sysprep de Windows (`sysprep_secret`).
`harvester_vm_snapshot`	Crear/listar/restaurar/eliminar instantáneas de VM. Restaurar acepta `halt_after_restore=true` para dejar la VM apagada.
`harvester_vm_backup`	Crear/listar/restaurar copias de seguridad de VM (Destino de copia de seguridad). Restaurar acepta `halt_after_restore=true`.
`harvester_image_list`	Listar imágenes de VM (VirtualMachineImage)
`harvester_image_create`	Crear imagen de VM desde URL (cuando no es solo lectura)
`harvester_volume_list`	Listar PVCs (volúmenes respaldados por Longhorn)
`harvester_volume_create`	Crear volumen/PVC (opcionalmente desde imagen)
`harvester_network_list`	Listar redes de VM (NetworkAttachmentDefinition)
`harvester_network_create`	Crear red de VM - superposición KubeOVN o VLAN (cuando no es solo lectura)
`harvester_network_update`	Actualizar configuración de red de VM (cuando no es solo lectura)
`harvester_network_delete`	Eliminar red de VM (cuando se permite destructivo)
`harvester_subnet_list`	Listar subredes KubeOVN (requiere kubeovn-operator)
`harvester_subnet_create`	Crear subred en VPC para red de VM (cuando no es solo lectura)
`harvester_subnet_update`	Actualizar namespaces/NAT de subred (cuando no es solo lectura)
`harvester_subnet_delete`	Eliminar subred (cuando se permite destructivo)
`harvester_host_list`	Listar nodos (hosts de Harvester)
`harvester_host_action`	Habilitar/deshabilitar modo de mantenimiento en un host (cordon/uncordon)
`harvester_settings`	Listar u obtener configuraciones de Harvester. Con `value`, o `pss_enabled` / `pss_whitelisted` / `pss_privileged` / `pss_restricted`, actualiza una configuración (incluyendo `cluster-pod-security-standard`) cuando no es solo lectura.
`harvester_addon_list`	Listar addons de Harvester (estado habilitado/deshabilitado)
`harvester_addon_switch`	Habilitar o deshabilitar un addon (cuando no es solo lectura)
`harvester_vpc_list`	Listar VPCs KubeOVN (requiere addon kubeovn-operator)
`harvester_vpc_create`	Crear un VPC KubeOVN (cuando no es solo lectura)
`harvester_vpc_update`	Actualizar namespaces de un VPC KubeOVN (cuando no es solo lectura)
`harvester_vpc_delete`	Eliminar un VPC KubeOVN (cuando se permite destructivo)
`harvester_vpc_nat_gateway`	Crear/listar/eliminar un gateway NAT de VPC Kube-OVN, EIP, regla DNAT o regla SNAT (`kind`: gateway, eip, dnat, snat)

Las herramientas de listado aceptan cluster (requerido), namespace, format (json|table), limit (predeterminado 100), continue (token de paginación para la siguiente página). Las herramientas de escritura requieren read_only: false.

Crear una VM en VPC KubeOVN con internet externo

Usa harvester_vm_create con:

network: Nombre de la red de superposición (NAD) vinculada a una subred KubeOVN. Crea a través de harvester_network_create (type=kubeovn) y luego harvester_subnet_create con provider={network}.{namespace}.ovn, vpc=<vpc-name> y nat_outgoing=true.
interface_type: managedtap (recomendado para KubeOVN) o bridge. Usa Multus como red principal.
subnet: Nombre opcional de subred KubeOVN para la anotación ovn.kubernetes.io/logical_switch.

Ejemplo: VM en la red vswitch1 en el namespace default, interfaz managedTap, subred vswitch1-subnet:

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

Herramientas de Rancher

Las herramientas de Rancher usan el clúster de gestión (local). No hay parámetro cluster en estas herramientas.

API Steve (recursos de gestión)

Herramienta	Descripción
`rancher_cluster_list`	Listar clústeres de Rancher (gestión)
`rancher_cluster_get`	Obtener un clúster (salud, versión, número de nodos)
`rancher_project_list`	Listar proyectos de Rancher
`rancher_overview`	Resumen: número de clústeres y número de proyectos

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

Las herramientas Norman llaman a la API de gestión JSON de Rancher. Descubre tipos y URLs de colección para tu servidor con rancher_norman_schema_list / rancher_norman_schema_get (ids de esquema como user, token, cluster).

Solo lectura (siempre registrado con el conjunto de herramientas rancher)

Herramienta	Descripción
`rancher_norman_schema_list`	Listar esquemas de API (`/v3/schemas`)
`rancher_norman_schema_get`	Obtener un esquema por id
`rancher_user_list` / `rancher_user_get`	Usuarios
`rancher_auth_config_list` / `rancher_auth_config_get`	Proveedores de autenticación (local, OIDC, etc.)
`rancher_token_list` / `rancher_token_get`	Tokens de API (valores redactados a menos que `--show-sensitive-data`)
`rancher_global_role_binding_list` / `rancher_global_role_binding_get`	Enlaces de roles globales
`rancher_cluster_registration_token_list` / `rancher_cluster_registration_token_get`	Tokens de registro de clúster
`rancher_node_driver_list`	Controladores de nodos
`rancher_cloud_credential_list` / `rancher_cloud_credential_get`	Credenciales en la nube (secretos redactados a menos que `--show-sensitive-data`)
`rancher_catalog_list` / `rancher_catalog_get`	Catálogos Norman heredados (`/v3/catalogs`)
`rancher_cluster_repo_list` / `rancher_cluster_repo_get`	Repositorios de clúster de catálogo de aplicaciones (ver nota a continuación)
`rancher_feature_flag_list` / `rancher_feature_flag_get`	Indicadores de características (`/v3/features`)
`rancher_setting_list` / `rancher_setting_get`	Configuraciones globales (`/v3/settings`)
`rancher_audit_log_list`	`GET /v3/auditlogs` cuando es compatible (a menudo 404/405; ver nota a continuación)

Cuando --read-only=false

Herramienta	Descripción
`rancher_norman_action`	`POST` un `?action=` de Norman en una ruta de recurso bajo `/v3`
`rancher_token_create`	Crear token de API
`rancher_auth_config_update`	Reemplazar una configuración de autenticación (`PUT`)
`rancher_user_create`	Crear usuario
`rancher_user_disable` / `rancher_user_enable`	Acciones de habilitar/deshabilitar usuario
`rancher_global_role_binding_create`	Crear vinculación de rol global
`rancher_cluster_registration_token_create`	Crear token de registro
`rancher_cloud_credential_create`	Crear credencial de nube
`rancher_catalog_refresh`	Actualizar catálogo heredado (`?action=refresh`)
`rancher_feature_flag_set`	Actualizar indicador de función (`PUT`)
`rancher_setting_update`	Actualizar configuración (`PUT`)
`rancher_supportbundle_generate`	Solicitar paquete de soporte (`generateSupportBundle` en un clúster)

Cuando --read-only=false y --disable-destructive=false

Herramienta	Descripción
`rancher_token_delete`	Eliminar token de API
`rancher_global_role_binding_delete`	Eliminar vinculación de rol global
`rancher_cluster_registration_token_delete`	Eliminar token de registro
`rancher_cloud_credential_delete`	Eliminar credencial de nube

Respuestas de Norman: catálogo, repositorios de clúster, auditoría

rancher_cluster_repo_list / rancher_cluster_repo_get: Intenta /v3/clusterrepos de Norman primero. Si devuelve 404 (común), recurre a catalog.cattle.io/v1 ClusterRepo en el clúster local mediante Steve/Kubernetes, probando los espacios de nombres cattle-global-data, fleet-default, fleet-local, cattle-fleet-system. El JSON de éxito incluye "_source":"kubernetes_api_fallback". Si nada funciona, la herramienta aún devuelve JSON estilo 200 con "_source":"unavailable" y errores por intento—no un error MCP duro—para que la automatización pueda continuar.
rancher_catalog_list / rancher_catalog_get: Si /v3/catalogs de Norman no está registrado (404), devuelve JSON con "_source":"unavailable" en lugar de fallar.
rancher_audit_log_list: Si el servidor devuelve 404 o 405 (GET no soportado), devuelve JSON con "_source":"unavailable" y _http_status; la auditoría puede estar deshabilitada o expuesta fuera de Norman.

Para datos de catálogo cuando ClusterRepo no está disponible en ningún lugar, use kubernetes_list en el clúster local con api_version catalog.cattle.io/v1 y kind ClusterRepo, o herramientas Helm / Fleet según corresponda.

Herramientas de Helm

Herramienta	Descripción
`helm_list`	Listar versiones de Helm (opcionalmente por espacio de nombres, desplegadas/fallidas/pendientes)
`helm_get`	Obtener detalles de la versión (manifiesto, valores, notas)
`helm_history`	Obtener historial de revisiones para una versión
`helm_repo_list`	Listar repositorios de gráficos Helm configurados (desde configuración local)
`helm_install`	Instalar un gráfico Helm (cuando no es de solo lectura)
`helm_upgrade`	Actualizar una versión de Helm (cuando no es de solo lectura)
`helm_rollback`	Revertir una versión a una revisión anterior (cuando no es de solo lectura)
`helm_uninstall`	Desinstalar una versión (cuando se permite destructivo)

Todas las herramientas toman cluster (ID de clúster de Rancher). Instalar/actualizar requieren chart, release; opcional repo_url, version, values (JSON).

Herramientas de Fleet

Herramienta	Descripción
`fleet_gitrepo_list`	Listar GitRepos de Fleet (fuentes GitOps)
`fleet_gitrepo_get`	Obtener un GitRepo (spec, status)
`fleet_gitrepo_create`	Crear un GitRepo (cuando no es de solo lectura)
`fleet_gitrepo_delete`	Eliminar un GitRepo (cuando se permite destructivo)
`fleet_gitrepo_action`	Pausar, reanudar, disablePolling, enablePolling, forceUpdate
`fleet_gitrepo_clone`	Clonar un GitRepo a un nuevo nombre (copiar spec)
`fleet_bundle_list`	Listar Bundles de Fleet (unidades de despliegue de GitRepos)
`fleet_cluster_list`	Listar clústeres de Fleet (clústeres downstream registrados con Fleet)
`fleet_drift_detect`	Reportar BundleDeployments con estado Modificado (deriva)

Todas las herramientas usan el clúster de gestión de Rancher (local). Opcional namespace (predeterminado: fleet-default). Las herramientas de listado soportan format, limit, continue (paginación). fleet_gitrepo_create requiere name, repo; opcional branch, paths. fleet_gitrepo_action soporta: pause, unpause, disablePolling, enablePolling, forceUpdate. fleet_gitrepo_clone copia spec de un GitRepo existente a un nuevo nombre.

Herramientas de Kubernetes

Herramienta	Descripción
`kubernetes_list`	Listar recursos por apiVersion/kind (p. ej. v1 Pod, apps/v1 Deployment)
`kubernetes_get`	Obtener un recurso por apiVersion, kind, espacio de nombres, nombre
`kubernetes_describe`	Obtener recurso + eventos recientes
`kubernetes_logs`	Obtener registros de pod recientes (solo cola; contenedor, tailLines, sinceSeconds)
`kubernetes_events`	Listar eventos en un espacio de nombres (filtro opcional involvedObject)
`kubernetes_capacity`	Resumen de capacidad/asignable de nodo por nodo
`kubernetes_create`	Crear recurso desde JSON (cuando no es de solo lectura)
`kubernetes_patch`	Aplicar parche a recurso con JSON (cuando no es de solo lectura)
`kubernetes_delete`	Eliminar recurso (cuando se permite destructivo)

Todas las herramientas toman cluster (ID de clúster de Rancher). Listar/obtener soportan namespace, format (json|table), limit, continue (paginación). Crear/aplicar parche/eliminar están controlados por read_only y disable_destructive. kubernetes_logs no soporta follow (transmisión); use tail_lines y since_seconds para limitar la salida. En algunas configuraciones de Rancher/proxy, los registros de pod pueden devolver 503 o errores de transmisión; consulte Solución de problemas.

Configuración: token de Rancher e ID de clúster de Harvester

Obtener un token de API de Rancher

Inicie sesión en su interfaz de Rancher.
Haga clic en su perfil/avatar (arriba a la derecha) → Cuenta y claves de API (o API y claves).
Haga clic en Crear clave de API, asígnele un nombre (p. ej. mcp-server), luego Crear.
Copie el token una vez (formato como token-abc12:xyz...). Úselo como --rancher-token o RANCHER_MCP_RANCHER_TOKEN.

Encontrar su ID de clúster de Harvester

Las herramientas de Harvester requieren el ID de clúster (p. ej. c-tx8rn) en cada llamada.

Desde la interfaz de Rancher: Vaya a Gestión de clústeres → abra su clúster de Harvester. La URL contiene el ID de clúster: .../c/<cluster-id>/....
Desde 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}'
Esquemas de Norman: curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_RANCHER_URL/v3/schemas" | jq '.data[0:5].id'

Docker (HTTP transmisible)

Para modo servidor HTTP, use la imagen de contenedor de GitHub Container Registry (ghcr.io). Para Cursor/Claude con stdio, use npm (consulte Inicio rápido).

Ejecute el servidor y exponga el puerto:

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 al endpoint MCP: `http://localhost:8080/mcp` (HTTP transmisible; la ruta predeterminada es `/mcp`). Ejemplo: `claude mcp add -t http rancher http://localhost:8080/mcp`

Plataformas compatibles

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

Solución de problemas

Problema	Qué verificar
"rancher-server-url and rancher-token are required"	Verifique `--rancher-server-url` y `--rancher-token` en los argumentos, o las variables de entorno `RANCHER_MCP_RANCHER_SERVER_URL` y `RANCHER_MCP_RANCHER_TOKEN`.
401 No autorizado	Token caducado o inválido. Cree una nueva clave de API en Rancher.
Errores TLS / certificado	Para Rancher con certificado autofirmado, pase `--tls-insecure` (solo desarrollo).
"cluster not found" o listas vacías	ID de clúster incorrecto. Obténgalo de la URL de la interfaz de Rancher o API; páselo como `cluster` a las herramientas de Harvester/Kubernetes.
Cursor no muestra herramientas	Reinicie Cursor después de editar `mcp.json`; verifique en Tools & MCP que el servidor esté habilitado.
Binario no encontrado	Use rutas absolutas en `mcp.json` para `command` al compilar desde el código fuente.
`kubernetes_logs` 503 o errores de transmisión	Conocido en algunas configuraciones de Rancher/proxy (p. ej. RKE2). Reduzca `tail_lines` o pruebe otro clúster; consulte rancher/rancher#40711.
La herramienta de Norman devuelve `"_source":"unavailable"`	Esa colección puede no existir en su versión de Rancher (p. ej. `catalogs` heredado, `clusterrepos`, o auditoría mediante `GET`). Use `rancher_norman_schema_list` para ver tipos registrados, o `kubernetes_list` / Helm / Fleet para fuentes de gráficos.
La lista de repositorios de clúster muestra `unavailable` o `data` vacío	`catalog.cattle.io` `ClusterRepo` puede no estar instalado o proxy para su token; pruebe `kubernetes_list` con `catalog.cattle.io/v1` y `ClusterRepo` en el clúster `local` en todos los espacios de nombres.

Licencia

Apache-2.0