Kubernetes MCP Server

Kubernetes MCP Server

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

Um servidor Model Context Protocol (MCP) para depuração e inspeção de Kubernetes. Este servidor fornece acesso somente leitura aos recursos do Kubernetes, sem a capacidade de criá-los ou modificá-los, tornando-o seguro para fins de depuração e monitoramento.

Recursos

• Acesso somente leitura: Inspecione recursos do Kubernetes com segurança, sem capacidades de modificação
• Suporte a CRD: Funciona com quaisquer Custom Resource Definitions (CRDs) no seu cluster
• Busca por substring: Descubra recursos por substring do grupo de API (ex.: "flux" para FluxCD, "argo" para ArgoCD)
• Ferramentas integradas:
  • list_resources: Listar e filtrar recursos do Kubernetes
  • describe_resource: Obter informações detalhadas sobre recursos específicos
  • get_pod_logs: Recuperar logs de pods com filtragem avançada
  • rollout_restart: Realizar um reinício contínuo (rolling restart) de um deployment do Kubernetes

Instalação

Pré-requisitos

• Acesso a um cluster Kubernetes (kubeconfig necessário)

Opção 1: Instalar com Go

Se você tiver o Go instalado, esta é a maneira mais fácil:

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

O binário será instalado 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

Se você preferir compilar a partir do código-fonte:

Requisitos:

• Go 1.24 ou posterior

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

Uso

Configuração

Para usar este servidor MCP, adicione-o ao seu arquivo de configuração:

Configuração básica (usa ~/.kube/config automaticamente):

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

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

Localização personalizada do kubeconfig:

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

Uso Manual

O servidor usa seu kubeconfig padrão para acesso ao cluster. Certifique-se de ter permissões de leitura adequadas para os recursos que deseja inspecionar.

./kubernetes-mcp

Ferramentas Disponíveis

1. list_resources

Listar recursos do Kubernetes com capacidades de filtragem.

Parâmetros:

• kind (obrigatório): Tipo de recurso (Pod, Deployment, Service, etc.) ou "all" para descoberta
• groupFilter (opcional): Filtrar por substring do grupo de API para descobrir recursos específicos do projeto
• namespace (opcional): Namespace alvo (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

Exemplo de uso:

{
  "kind": "Pod",
  "namespace": "default",
  "labelSelector": "app=nginx"
}

Modo de descoberta:

{
  "kind": "all",
  "groupFilter": "flux"
}

2. describe_resource

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

Parâmetros:

• kind (obrigatório): Tipo de recurso
• name (obrigatório): Nome do recurso
• namespace (opcional): Namespace alvo

Exemplo de uso:

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

3. get_pod_logs

Recuperar logs de pods com várias opções de filtragem.

Parâmetros:

• 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 a partir do final (padrão: 100)
• since (opcional): Duração como "5s", "2m", "3h"
• sinceTime (opcional): Timestamp RFC3339
• timestamps (opcional): Incluir timestamps
• previous (opcional): Obter logs da instância anterior do contêiner

Exemplo de uso:

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

Principais Recursos

Suporte a CRD

O servidor descobre e trabalha automaticamente com quaisquer Custom Resource Definitions no seu cluster. Basta usar o nome do Kind do CRD com as ferramentas list_resources ou describe_resource.

Descoberta de Recursos

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

• "flux" - Descobrir recursos FluxCD (HelmReleases, Kustomizations, etc.)
• "argo" - Descobrir recursos ArgoCD (Applications, AppProjects, etc.)
• "istio" - Descobrir recursos Istio (VirtualServices, DestinationRules, etc.)
• "cert-manager" - Descobrir recursos cert-manager (Certificates, Issuers, etc.)

Segurança em Primeiro Lugar

Este servidor foi projetado apenas para depuração e inspeção:

• Sem capacidades de criação, modificação ou exclusão de recursos
• Acesso somente leitura aos recursos do cluster
• Seguro para uso em ambientes de produção para monitoramento

Contribuição

Este projeto é open source e aceita contribuições. Por favor, garanta que todas as alterações mantenham a natureza somente leitura do servidor.

Licença

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

Suporte