Kubernetes

mcp-kubernetes

O mcp-kubernetes é um servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam com clusters Kubernetes. Ele atua como uma ponte entre ferramentas de IA (como Claude, Cursor e GitHub Copilot) e o Kubernetes, traduzindo solicitações em linguagem natural em operações Kubernetes e retornando os resultados em um formato que as ferramentas de IA possam entender.

Ele permite que ferramentas de IA:

• Consultem recursos Kubernetes
• Executem comandos kubectl
• Gerenciem clusters Kubernetes por meio de interações em linguagem natural
• Diagnosticem e interpretem os estados dos recursos Kubernetes

Como funciona

Como instalar

Imagens de contêiner não são mais produzidas ou suportadas. Instale um binário de versão publicada localmente e configure seu cliente MCP para executá-lo como um subprocesso stdio.

Local

# For Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# For MacOS
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Configure seus servidores MCP no Claude Desktop, Cursor, ChatGPT Copilot, Github Copilot e outros clientes de IA suportados, por exemplo:

{
  "mcpServers": {
    "kubernetes": {
      "command": "<path of binary 'mcp-kubernetes'>",
      "args": ["--transport", "stdio"],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

Opções

Variáveis de ambiente:

• KUBECONFIG: Caminho para o seu arquivo kubeconfig, ex.: /home/<username>/.kube/config.
• USE_LEGACY_TOOLS: Defina como true para usar várias ferramentas kubectl especializadas em vez da ferramenta unificada call_kubectl (padrão: false).

Argumentos de linha de comando:

Usage of ./mcp-kubernetes:
      --access-level string       Access level (readonly, readwrite, or admin) (default "readonly")
      --additional-tools string   Comma-separated list of additional tools to support (kubectl is always enabled). Available: helm,cilium,hubble
      --allow-namespaces string   Comma-separated list of namespaces to allow (empty means all allowed)
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "")
      --timeout int               Timeout for command execution in seconds, default is 60s (default 60)
      --transport string          Transport mechanism to use (stdio only) (default "stdio")

Ferramentas Unificadas vs. Legadas

Por padrão, o mcp-kubernetes usa uma única ferramenta unificada call_kubectl que consolida todas as operações kubectl em uma única interface de ferramenta. Isso reduz significativamente o consumo de contexto, mantendo a funcionalidade completa.

Para usar o modo legado com várias ferramentas especializadas (6 a 7 ferramentas separadas), defina a variável de ambiente:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "USE_LEGACY_TOOLS": "true"
      }
    }
  }
}

Níveis de Acesso

A flag --access-level controla quais operações são permitidas:

• readonly (padrão): Apenas operações de leitura são permitidas (get, describe, logs, etc.)
• readwrite: Operações de leitura e escrita são permitidas (create, delete, apply, etc.)
• admin: Todas as operações são permitidas, incluindo operações de administração (cordon, drain, taint, etc.)

As ferramentas e operações são filtradas no momento do registro com base no nível de acesso, para que os assistentes de IA vejam apenas as operações que podem realmente usar.

Exemplos de configuração:

// Read-only access (default)
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes"
    }
  }
}

// Read-write access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "readwrite"]
    }
  }
}

// Admin access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "admin"]
    }
  }
}

Uso

Faça qualquer pergunta sobre o cluster Kubernetes no seu cliente de IA. As ferramentas MCP facilitam que os assistentes de IA entendam e usem operações kubectl.

Exemplos de Consultas

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Show me all deployments in the production namespace

Scale my web deployment to 5 replicas

Check if I have permission to create pods

What is my current kubectl context?

List all available kubectl contexts

Switch to the production context

Ferramentas Disponíveis

Ferramenta Unificada (Padrão)

Por padrão, o mcp-kubernetes usa uma única ferramenta unificada call_kubectl que lida com todas as operações kubectl. Essa abordagem reduz significativamente o consumo de contexto em comparação com a abordagem legada de múltiplas ferramentas.

call_kubectl - Executa comandos kubectl

• Disponível em: Todos os níveis de acesso (operações filtradas por nível de acesso)
• Parâmetros:
  • command: O comando kubectl completo a ser executado, incluindo o prefixo 'kubectl' (ex.: "kubectl get pods -n default", "kubectl apply -f deployment.yaml")
• Exemplos:

  # Get pods
  command: "kubectl get pods -n default"
  
  # Apply configuration
  command: "kubectl apply -f deployment.yaml"
  
  # Scale deployment
  command: "kubectl scale deployment nginx --replicas=3"
  

Ferramentas Legadas (Opcional)

Quando USE_LEGACY_TOOLS=true, o servidor mcp-kubernetes fornece várias ferramentas kubectl especializadas que agrupam operações relacionadas. As ferramentas são filtradas automaticamente com base no seu nível de acesso.

Ferramentas Kubectl

# Get all pods
operation: "get"
resource: "pods"
args: "--all-namespaces"

# Apply a configuration
operation: "apply"
resource: ""
args: "-f deployment.yaml"

# Drain a node (admin only)
operation: "drain"
resource: "node"
args: "worker-1 --ignore-daemonsets"

# Add a taint (admin only)
operation: "taint"
resource: "nodes"
args: "worker-1 key=value:NoSchedule"

# Scale a deployment
operation: "scale"
resource: "deployment"
args: "nginx --replicas=3"

# Check rollout status
operation: "rollout"
resource: "status"
args: "deployment/nginx"

# Add a label
operation: "label"
resource: "pods"
args: "nginx-pod app=web"

# Set image
operation: "set"
resource: "image"
args: "deployment/nginx nginx=nginx:latest"

# View logs
operation: "logs"
resource: ""
args: "nginx-pod -f"

# Execute command in pod
operation: "exec"
resource: ""
args: "nginx-pod -- ls /app"

# Get cluster info
operation: "cluster-info"
resource: ""
args: ""

# Explain pod spec
operation: "explain"
resource: "pod.spec"
args: "--recursive"

# Check permissions
operation: "auth"
resource: "can-i"
args: "create pods"

# Approve certificate
operation: "certificate"
resource: "approve"
args: "csr-name"

# Get current context
operation: "config"
resource: "current-context"
args: ""

# List all contexts
operation: "config"
resource: "get-contexts"
args: ""

# Switch context (readwrite/admin only)
operation: "config"
resource: "use-context"
args: "my-cluster-context"

Ferramentas Adicionais

command: "list --all-namespaces"

command: "status"

command: "status"
command: "observe observe --namespace backend-jobs  --from-label 'app=web'"
command: "list nodes"

Telemetria

A coleta de telemetria está ativada por padrão.

Para desativar, defina a variável de ambiente KUBERNETES_MCP_COLLECT_TELEMETRY=false.

Suporte a OpenTelemetry

O servidor mcp-kubernetes suporta a exportação de dados de telemetria usando o Protocolo OpenTelemetry (OTLP). Você pode configurar um endpoint OTLP para enviar traces a qualquer backend compatível com OpenTelemetry:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--otlp-endpoint", "localhost:4317"]
    }
  }
}

Desenvolvimento

Como inspecionar solicitações e respostas do servidor MCP:

npx @modelcontextprotocol/inspector <path of binary 'mcp-kubernetes'>

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um Contrato de Licença de Contribuidor (CLA) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para mais detalhes, visite https://cla.opensource.microsoft.com.

Ao enviar um pull request, um bot de CLA determinará automaticamente se você precisa fornecer um CLA e decorará o PR adequadamente (ex.: verificação de status, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Código Aberto da Microsoft. Para mais informações, consulte as Perguntas Frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Marcas Registradas

Este projeto pode conter marcas registradas ou logotipos de projetos, produtos ou serviços. O uso autorizado de marcas registradas ou logotipos da Microsoft está sujeito e deve seguir as Diretrizes de Marca Registrada e Marca da Microsoft. O uso de marcas registradas ou logotipos da Microsoft em versões modificadas deste projeto não deve causar confusão ou implicar patrocínio da Microsoft. Qualquer uso de marcas registradas ou logotipos de terceiros está sujeito às políticas desses terceiros.