Kubernetes MCP Server

Kubernetes MCP Server

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

Um servidor Model Context Protocol (MCP) que fornece acesso seguro e somente leitura aos recursos Kubernetes para depuração e inspeção. Construído com segurança em mente, oferece visibilidade abrangente do cluster sem capacidades de modificação.

Recursos

• 🔒 Segurança somente leitura: Inspecione recursos Kubernetes com segurança, sem capacidades de modificação
• 🎯 Suporte a CRD: Funciona perfeitamente com qualquer Custom Resource Definition no seu cluster
• 🌐 Suporte a múltiplos clusters: Alterne entre diferentes contextos Kubernetes sem interrupções
• 🔍 Descoberta inteligente: Encontre recursos por substring do grupo de API (ex.: "flux" para FluxCD, "argo" para ArgoCD)
• ⚡ Alto desempenho: Consulta eficiente de recursos com filtragem e paginação
• 🛠️ Conjunto abrangente de ferramentas:
  • list_resources: Liste e filtre recursos Kubernetes com opções avançadas
  • describe_resource: Obtenha informações detalhadas sobre recursos específicos
  • get_pod_logs: Recupere logs de pods com capacidades sofisticadas de filtragem
  • list_events: Liste e filtre eventos Kubernetes para depuração e monitoramento
  • list_contexts: Liste todos os contextos Kubernetes disponíveis do kubeconfig

🚀 Início Rápido

Pré-requisitos

• Acesso ao cluster Kubernetes com um arquivo kubeconfig válido
• Go 1.24+ (para compilar a partir do código-fonte)

Opções de Instalação

Opção 1: Instalar com Go (Recomendado)

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

O binário estará disponível em $GOPATH/bin/kubernetes-mcp (ou $HOME/go/bin/kubernetes-mcp se GOPATH não estiver definido).

Opção 2: Compilar a partir do Código-Fonte

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

⚙️ Configuração

Configuração do Servidor MCP

Adicione o servidor à sua configuração MCP:

Configuração Básica

Usa ~/.kube/config automaticamente:

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

Kubeconfig Personalizado

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

Nota: Substitua /path/to/kubernetes-mcp pelo caminho real do seu binário.

Uso Independente

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

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

Importante: Certifique-se de ter permissões de leitura adequadas para os recursos Kubernetes que deseja inspecionar.

🛠️ Ferramentas Disponíveis

list_resources

Liste e filtre recursos Kubernetes com capacidades avançadas.

Parâmetro	Tipo	Descrição
context	opcional	Nome do contexto Kubernetes do kubeconfig (deixe vazio para o contexto atual)
kind	obrigatório	Tipo de recurso (Pod, Deployment, Service, etc.) ou "all" para descoberta
groupFilter	opcional	Filtrar por substring do grupo de API para recursos específicos do projeto
namespace	opcional	Namespace de destino (padrão: todos os namespaces)
labelSelector	opcional	Filtrar por labels (ex.: "app=nginx")
fieldSelector	opcional	Filtrar por campos (ex.: "metadata.name=my-pod")
limit	opcional	Número máximo de recursos a retornar
timeoutSeconds	opcional	Tempo limite da solicitação (padrão: 30s)
showDetails	opcional	Retornar objetos de recurso completos em vez de resumo

Exemplos:

// 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

Obtenha informações detalhadas sobre um recurso Kubernetes específico.

Parâmetro	Tipo	Descrição
context	opcional	Nome do contexto Kubernetes do kubeconfig (deixe vazio para o contexto atual)
kind	obrigatório	Tipo de recurso (Pod, Deployment, etc.)
name	obrigatório	Nome do recurso
namespace	opcional	Namespace de destino

Exemplo:

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

get_pod_logs

Recupere logs de pods com opções sofisticadas de filtragem.

Parâmetro	Tipo	Descrição
context	opcional	Nome do contexto Kubernetes do kubeconfig (deixe vazio para o contexto atual)
name	obrigatório	Nome do pod
namespace	opcional	Namespace do pod (padrão: "default")
container	opcional	Nome do contêiner específico
tail	opcional	Número de linhas do final (padrão: 100)
since	opcional	Duração como "5s", "2m", "3h"
sinceTime	opcional	Timestamp RFC3339
timestamps	opcional	Incluir timestamps na saída
previous	opcional	Obter logs da instância anterior do contêiner

Exemplo:

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

list_events

Liste e filtre eventos Kubernetes com opções avançadas de filtragem para depuração e monitoramento.

Parâmetro	Tipo	Descrição
context	opcional	Nome do contexto Kubernetes do kubeconfig (deixe vazio para o contexto atual)
namespace	opcional	Namespace de destino (deixe vazio para todos os namespaces)
object	opcional	Filtrar por nome do objeto (ex.: nome do pod, nome do deployment)
eventType	opcional	Filtrar por tipo de evento: "Normal" ou "Warning" (sem diferenciar maiúsculas/minúsculas)
reason	opcional	Filtrar por motivo do evento (ex.: "Pulled", "Failed", "FailedScheduling")
since	opcional	Duração como "5s", "2m", "1h"
sinceTime	opcional	Timestamp RFC3339 (ex.: "2025-06-20T10:00:00Z")
limit	opcional	Número máximo de eventos a retornar (padrão: 100)
timeoutSeconds	opcional	Tempo limite da solicitação (padrão: 30s)

Exemplos:

// 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 os contextos Kubernetes disponíveis do seu arquivo kubeconfig.

Parâmetros: Nenhum - esta ferramenta não aceita parâmetros.

Exemplo de Resposta:

{
  "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: Perfeito para fluxos de trabalho com múltiplos clusters onde você precisa:

• Descobrir contextos Kubernetes disponíveis
• Identificar o contexto ativo atual
• Planejar operações em vários clusters

🌟 Recursos Avançados

🌐 Suporte a Múltiplos Clusters

Trabalhe perfeitamente com vários clusters Kubernetes usando alternância de contexto:

• Parâmetro de Contexto: Todas as ferramentas agora suportam um parâmetro opcional context para especificar qual cluster consultar
• Descoberta Automática: Usa seu arquivo kubeconfig existente e descobre automaticamente os contextos disponíveis
• Contexto Padrão: Quando nenhum contexto é especificado, usa o contexto atual do seu kubeconfig
• Conexões em Cache: Gerencia eficientemente conexões com vários clusters usando cache de conexões

Exemplos com múltiplos clusters:

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

🎯 Suporte a Custom Resource Definition (CRD)

Descobre e trabalha automaticamente com qualquer CRD no seu cluster. Basta usar o nome do Kind do CRD com as ferramentas list_resources ou describe_resource.

🔍 Descoberta Inteligente de Recursos

Use o parâmetro groupFilter para descobrir recursos por substring do grupo de API:

Filtro	Descobre	Exemplos
"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

🔒 Segurança e Proteção

Construído com a segurança como preocupação principal:

• ✅ Acesso somente leitura - Sem criação, modificação ou exclusão de recursos
• ✅ Seguro para produção - Seguro para uso em ambientes de produção
• ✅ Permissões mínimas - Requer apenas acesso de leitura aos recursos do cluster
• ✅ Sem operações destrutivas - Não pode danificar seu cluster

---

🤝 Contribuindo

Aceitamos contribuições! Por favor, garanta que todas as alterações mantenham a natureza somente leitura do servidor e incluam testes apropriados.

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.