Kubernetes MCP Server

Proporciona acceso seguro y de solo lectura a los recursos del clúster de Kubernetes para depuración e inspección.

Documentación

Kubernetes MCP Server

https://github.com/user-attachments/assets/89df70b0-65d1-461c-b4ab-84b2087136fa

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso seguro y de solo lectura a los recursos de Kubernetes para depuración e inspección. Construido con la seguridad en mente, ofrece visibilidad integral del clúster sin capacidades de modificación.

Características

🔒 Seguridad de solo lectura: Inspeccione recursos de Kubernetes de forma segura sin capacidades de modificación
🎯 Soporte para CRD: Funciona sin problemas con cualquier Definición de Recurso Personalizado en su clúster
🌐 Soporte multi-clúster: Cambie entre diferentes contextos de Kubernetes sin problemas
🔍 Descubrimiento inteligente: Encuentre recursos por subcadena de grupo de API (por ejemplo, "flux" para FluxCD, "argo" para ArgoCD)
⚡ Alto rendimiento: Consulta eficiente de recursos con filtrado y paginación
🛠️ Conjunto de herramientas integral:
- list_resources: Liste y filtre recursos de Kubernetes con opciones avanzadas
- describe_resource: Obtenga información detallada sobre recursos específicos
- get_pod_logs: Recupere registros de pods con capacidades de filtrado sofisticadas
- list_events: Liste y filtre eventos de Kubernetes para depuración y monitoreo
- list_contexts: Liste todos los contextos de Kubernetes disponibles desde kubeconfig

🚀 Inicio Rápido

Requisitos Previos

Acceso al clúster de Kubernetes con un archivo kubeconfig válido
Go 1.24+ (para compilar desde el código fuente)

Opciones de Instalación

Opción 1: Instalar con Go (Recomendado)

go install github.com/kkb0318/kubernetes-mcp@latest

El binario estará disponible en $GOPATH/bin/kubernetes-mcp (o $HOME/go/bin/kubernetes-mcp si GOPATH no está configurado).

Opción 2: Compilar desde el Código Fuente

git clone https://github.com/kkb0318/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp .

⚙️ Configuración

Configuración del Servidor MCP

Agregue el servidor a su configuración de MCP:

Configuración Básica

Usa ~/.kube/config automáticamente:

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp"
    }
  }
}

Kubeconfig Personalizado

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp",
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

Nota: Reemplace /path/to/kubernetes-mcp con la ruta real de su binario.

Uso Independiente

# Default kubeconfig (~/.kube/config)
./kubernetes-mcp

# Custom kubeconfig path
KUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp

Importante: Asegúrese de tener permisos de lectura apropiados para los recursos de Kubernetes que desea inspeccionar.

🛠️ Herramientas Disponibles

`list_resources`

Liste y filtre recursos de Kubernetes con capacidades avanzadas.

Parámetro	Tipo	Descripción
`context`	opcional	Nombre del contexto de Kubernetes desde kubeconfig (déjelo vacío para el contexto actual)
`kind`	requerido	Tipo de recurso (Pod, Deployment, Service, etc.) o "all" para descubrimiento
`groupFilter`	opcional	Filtre por subcadena de grupo de API para recursos específicos del proyecto
`namespace`	opcional	Namespace de destino (por defecto, todos los namespaces)
`labelSelector`	opcional	Filtre por etiquetas (por ejemplo, "app=nginx")
`fieldSelector`	opcional	Filtre por campos (por ejemplo, "metadata.name=my-pod")
`limit`	opcional	Número máximo de recursos a devolver
`timeoutSeconds`	opcional	Tiempo de espera de la solicitud (por defecto: 30s)
`showDetails`	opcional	Devuelva objetos de recurso completos en lugar de un resumen

Ejemplos:

// List pods with label selector
{
  "kind": "Pod",
  "namespace": "default",
  "labelSelector": "app=nginx"
}

// List pods from a specific cluster context
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// Discover FluxCD resources
{
  "kind": "all",
  "groupFilter": "flux"
}

`describe_resource`

Obtenga información detallada sobre un recurso específico de Kubernetes.

Parámetro	Tipo	Descripción
`context`	opcional	Nombre del contexto de Kubernetes desde kubeconfig (déjelo vacío para el contexto actual)
`kind`	requerido	Tipo de recurso (Pod, Deployment, etc.)
`name`	requerido	Nombre del recurso
`namespace`	opcional	Namespace de destino

Ejemplo:

{
  "kind": "Pod",
  "name": "nginx-pod",
  "namespace": "default"
}

`get_pod_logs`

Recupere registros de pods con opciones de filtrado sofisticadas.

Parámetro	Tipo	Descripción
`context`	opcional	Nombre del contexto de Kubernetes desde kubeconfig (déjelo vacío para el contexto actual)
`name`	requerido	Nombre del pod
`namespace`	opcional	Namespace del pod (por defecto: "default")
`container`	opcional	Nombre del contenedor específico
`tail`	opcional	Número de líneas desde el final (por defecto: 100)
`since`	opcional	Duración como "5s", "2m", "3h"
`sinceTime`	opcional	Marca de tiempo RFC3339
`timestamps`	opcional	Incluya marcas de tiempo en la salida
`previous`	opcional	Obtenga registros de la instancia de contenedor anterior

Ejemplo:

{
  "name": "nginx-pod",
  "namespace": "default",
  "tail": 50,
  "since": "5m",
  "timestamps": true
}

`list_events`

Liste y filtre eventos de Kubernetes con opciones de filtrado avanzadas para depuración y monitoreo.

Parámetro	Tipo	Descripción
`context`	opcional	Nombre del contexto de Kubernetes desde kubeconfig (déjelo vacío para el contexto actual)
`namespace`	opcional	Namespace de destino (déjelo vacío para todos los namespaces)
`object`	opcional	Filtre por nombre de objeto (por ejemplo, nombre de pod, nombre de deployment)
`eventType`	opcional	Filtre por tipo de evento: "Normal" o "Warning" (sin distinción de mayúsculas)
`reason`	opcional	Filtre por motivo del evento (por ejemplo, "Pulled", "Failed", "FailedScheduling")
`since`	opcional	Duración como "5s", "2m", "1h"
`sinceTime`	opcional	Marca de tiempo RFC3339 (por ejemplo, "2025-06-20T10:00:00Z")
`limit`	opcional	Número máximo de eventos a devolver (por defecto: 100)
`timeoutSeconds`	opcional	Tiempo de espera de la solicitud (por defecto: 30s)

Ejemplos:

// List recent warning events
{
  "eventType": "Warning",
  "since": "30m"
}

// List events for a specific pod
{
  "object": "nginx-pod",
  "namespace": "default"
}

// List failed scheduling events
{
  "reason": "FailedScheduling",
  "limit": 50
}

`list_contexts`

Liste todos los contextos de Kubernetes disponibles desde su archivo kubeconfig.

Parámetros: Ninguno: esta herramienta no acepta parámetros.

Ejemplo de Respuesta:

{
  "contexts": [
    {
      "name": "production-cluster",
      "is_current": false
    },
    {
      "name": "staging-cluster", 
      "is_current": true
    },
    {
      "name": "development-cluster",
      "is_current": false
    }
  ],
  "current_context": "staging-cluster",
  "total": 3
}

Caso de Uso: Perfecto para flujos de trabajo multi-clúster donde necesita:

Descubrir contextos de Kubernetes disponibles
Identificar el contexto activo actual
Planificar operaciones en múltiples clústeres

🌟 Características Avanzadas

🌐 Soporte Multi-Clúster

Trabaje sin problemas con múltiples clústeres de Kubernetes usando cambio de contexto:

Parámetro de Contexto: Todas las herramientas ahora admiten un parámetro opcional context para especificar qué clúster consultar
Descubrimiento Automático: Usa su archivo kubeconfig existente y descubre automáticamente los contextos disponibles
Contexto Predeterminado: Cuando no se especifica ningún contexto, usa el contexto actual de su kubeconfig
Conexiones en Caché: Gestiona eficientemente conexiones a múltiples clústeres con caché de conexiones

Ejemplos Multi-clúster:

// Query production cluster
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// Get logs from staging environment
{
  "name": "api-server",
  "context": "staging-cluster",
  "namespace": "api"
}

// Compare resources across environments (use multiple calls)
{
  "kind": "Deployment",
  "context": "production-cluster",
  "namespace": "app"
}

🎯 Soporte para Definiciones de Recursos Personalizados (CRD)

Descubre y trabaja automáticamente con cualquier CRD en su clúster. Simplemente use el nombre de Kind del CRD con las herramientas list_resources o describe_resource.

🔍 Descubrimiento Inteligente de Recursos

Use el parámetro groupFilter para descubrir recursos por subcadena de grupo de API:

Filtro	Descubre	Ejemplos
`"flux"`	Recursos FluxCD	HelmReleases, Kustomizations, GitRepositories
`"argo"`	Recursos ArgoCD	Applications, AppProjects, ApplicationSets
`"istio"`	Recursos Istio	VirtualServices, DestinationRules, Gateways
`"cert-manager"`	Recursos cert-manager	Certificates, Issuers, ClusterIssuers

🔒 Seguridad y Protección

Construido con la seguridad como preocupación principal:

✅ Acceso de solo lectura - Sin creación, modificación o eliminación de recursos
✅ Seguro para producción - Seguro para usar en entornos de producción
✅ Permisos mínimos - Solo requiere acceso de lectura a los recursos del clúster
✅ Sin operaciones destructivas - No puede dañar su clúster

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Asegúrese de que todos los cambios mantengan la naturaleza de solo lectura del servidor e incluyan pruebas apropiadas.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para obtener más detalles.