Kubernetes

Conecte-se ao cluster Kubernetes e gerencie pods, deployments, serviços.

GitHub
1.6k
Experimente este MCPPatrocinado

Documentação

Servidor MCP Kubernetes

CI Language Kubernetes Docker Stars Issues PRs Welcome Last Commit

Servidor MCP que pode conectar a um cluster Kubernetes e gerenciá-lo. Suporta carregamento de kubeconfig de múltiplas fontes em ordem de prioridade.

https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed

Instalação e Uso

Pré-requisitos

Antes de usar este servidor MCP com qualquer ferramenta, certifique-se de ter:

  1. kubectl instalado e no seu PATH
  2. Um arquivo kubeconfig válido com contextos configurados
  3. Acesso a um cluster Kubernetes configurado para kubectl (ex.: minikube, Rancher Desktop, GKE, etc.)
  4. Helm v3 instalado e no seu PATH (sem Tiller). Opcional se você não planeja usar Helm.

Você pode verificar sua conexão executando kubectl get pods em um terminal para garantir que possa conectar ao seu cluster sem problemas de credenciais.

Por padrão, o servidor carrega o kubeconfig de ~/.kube/config. Para opções adicionais de autenticação (variáveis de ambiente, caminhos customizados, etc.), consulte ADVANCED_README.md.

Claude Code

Adicione o servidor MCP ao Claude Code usando o comando integrado:

claude mcp add kubernetes -- npx mcp-server-kubernetes

Isso configurará automaticamente o servidor nas configurações do MCP do seu Claude Code.

Codex

Adicione o servidor MCP ao Codex CLI usando o comando integrado:

codex mcp add kubernetes -- npx mcp-server-kubernetes

Isso registra o servidor globalmente em ~/.codex/config.toml e disponibiliza suas ferramentas em todas as sessões do Codex.

Claude Desktop

Adicione a seguinte configuração ao arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

Claude Desktop Connector via mcpb

O Servidor MCP Kubernetes também está disponível como uma extensão mcpb (anteriormente dxt). No Claude Desktop, vá para Configurações (Cmd+, no Mac) -> Extensões -> Procurar Extensões e role para encontrar mcp-server-kubernetes no modal. Instale-o e ele instalará e utilizará o kubectl via linha de comando e seu kubeconfig.

Para instalar manualmente, você também pode obter o .mcpb indo até o mais recente Release e baixando-o.

VS Code

Install Kubernetes MCP in VS Code

Para integração com VS Code, você pode usar o servidor MCP com extensões que suportam o Model Context Protocol:

  1. Instale uma extensão MCP compatível (como Claude Dev ou clientes MCP similares)
  2. Configure a extensão para usar este servidor:
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "description": "Kubernetes cluster management and operations"
    }
  }
}

Cursor

O Cursor suporta servidores MCP através de sua integração de IA. Adicione o servidor à sua configuração de MCP do Cursor:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

O servidor se conectará automaticamente ao seu contexto kubectl atual. Você pode verificar a conexão pedindo ao assistente de IA para listar seus pods ou criar um deployment de teste.

Uso com mcp-chat

mcp-chat é um cliente de chat em CLI para servidores MCP. Você pode usá-lo para interagir com o servidor Kubernetes.

npx mcp-chat --server "npx mcp-server-kubernetes"

Alternativamente, passe a ele seu arquivo de configuração do Claude Desktop existente acima (Linux deve passar o caminho correto para config):

Mac:

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

Recursos

  • Conectar a um cluster Kubernetes
  • API kubectl unificada para gerenciamento de recursos
    • Obter ou listar recursos com kubectl_get
    • Descrever recursos com kubectl_describe
    • Listar recursos com kubectl_get
    • Criar recursos com kubectl_create
    • Aplicar manifestos YAML com kubectl_apply
    • Excluir recursos com kubectl_delete
    • Obter logs com kubectl_logs
    • Gerenciar contextos kubectl com kubectl_context
    • Explicar recursos Kubernetes com explain_resource
    • Listar recursos de API com list_api_resources
    • Escalar recursos com kubectl_scale
    • Atualizar campo(s) de um recurso com kubectl_patch
    • Gerenciar rollouts de deployment com kubectl_rollout
    • Executar qualquer comando kubectl com kubectl_generic
    • Verificar conexão com ping
  • Operações avançadas
    • Escalar deployments com kubectl_scale (substitui o legado scale_deployment)
    • Port forward para pods e serviços com port_forward
    • Executar operações Helm
      • Instalar, atualizar e desinstalar charts
      • Suporte para valores customizados, repositórios e versões
      • Instalação baseada em template (helm_template_apply) para contornar problemas de autenticação
      • Desinstalação baseada em template (helm_template_uninstall) para contornar problemas de autenticação
    • Operações de limpeza de pods
      • Limpar pods problemáticos (cleanup_pods) nos estados: Evicted, ContainerStatusUnknown, Completed, Error, ImagePullBackOff, CrashLoopBackOff
    • Operações de gerenciamento de nós
      • Cordon, drain e uncordon de nós (node_management) para operações de manutenção e escalonamento
  • Prompt de Solução de Problemas (k8s-diagnose)
    • Guia através de um fluxo sistemático de solução de problemas Kubernetes para pods com base em uma palavra-chave e namespace opcional.
  • Modo não destrutivo para acesso somente leitura e criação/atualização de clusters
  • Mascaramento de segredos para segurança (mascara dados sensíveis em comandos kubectl get secrets, não afeta logs)
  • Observabilidade OpenTelemetry (opt-in)
    • Rastreamento distribuído para todas as chamadas de ferramentas
    • Exportação para Jaeger, Tempo, Grafana ou qualquer backend OTLP
    • Estratégias de amostragem configuráveis
    • Atributos de span ricos (nome da ferramenta, duração, contexto K8s, erros)
    • Consulte docs/OBSERVABILITY.md para detalhes

Observabilidade

O servidor MCP Kubernetes inclui integração OpenTelemetry opcional para observabilidade abrangente. Este recurso está desabilitado por padrão e pode ser habilitado via variáveis de ambiente ou configuração Helm.

Início Rápido

Habilite a observabilidade com variáveis de ambiente:

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

npx mcp-server-kubernetes

O Que é Rastreado

  • Todas as chamadas de ferramentas: kubectl_get, kubectl_apply, kubectl_logs, etc.
  • Duração da execução: Quanto tempo cada operação leva
  • Status de sucesso/falha: Rastreamento automático de erros
  • Contexto Kubernetes: Namespace, contexto, tipo de recurso
  • Metadados ricos: Host, processo e atributos customizados

Backends Suportados

Funciona com qualquer backend compatível com OTLP:

  • Jaeger (open source)
  • Grafana Tempo (open source)
  • Grafana Cloud (comercial)
  • Datadog, New Relic, Honeycomb, Lightstep, AWS X-Ray

Configuração

Consulte docs/OBSERVABILITY.md para documentação abrangente, incluindo:

  • Opções de configuração
  • Exemplos de implantação (Kubernetes, Helm, Claude Code)
  • Estratégias de amostragem
  • Melhores práticas de produção
  • Guia de solução de problemas

Exemplo com Jaeger

# Start Jaeger
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Enable telemetry
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_TRACES_SAMPLER=always_on

# Run server
npx mcp-server-kubernetes

# View traces: http://localhost:16686

Prompts

O servidor MCP Kubernetes inclui prompts especializados para auxiliar em operações comuns de diagnóstico.

Prompt /k8s-diagnose

Este prompt fornece um fluxo sistemático de solução de problemas para pods Kubernetes. Ele aceita um keyword para identificar pods relevantes e um namespace opcional para restringir a busca. A saída do prompt guiará você por um fluxo autônomo de solução de problemas, fornecendo instruções para identificar problemas, coletar evidências e sugerir etapas de correção.

Desenvolvimento Local

Certifique-se de que você tenha bun instalado. Clone o repositório e instale as dependências:

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

Fluxo de Desenvolvimento

  1. Inicie o servidor em modo de desenvolvimento (observa mudanças de arquivos):
bun run dev
  1. Execute testes unitários:
bun run test
  1. Construa o projeto:
bun run build
  1. Teste local com Inspector
npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link
  1. Teste local com Claude Desktop
{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
    }
  }
}
  1. Teste local com mcp-chat
bun run chat

Contribuindo

Consulte o arquivo CONTRIBUTING.md para detalhes.

Avançado

Modo Não Destrutivo

Você pode executar o servidor em um modo não destrutivo que desabilita todas as operações destrutivas (excluir pods, excluir deployments, excluir namespaces, etc.):

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

Para configuração do Claude Desktop com modo não destrutivo:

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

Comandos Disponíveis no Modo Não Destrutivo

Todas as operações somente leitura e de criação/atualização de recursos permanecem disponíveis:

  • Informação de Recursos: kubectl_get, kubectl_describe, kubectl_logs, explain_resource, list_api_resources
  • Criação/Modificação de Recursos: kubectl_apply, kubectl_create, kubectl_scale, kubectl_patch, kubectl_rollout
  • Operações Helm: install_helm_chart, upgrade_helm_chart, helm_template_apply, helm_template_uninstall
  • Conectividade: port_forward, stop_port_forward
  • Gerenciamento de Contexto: kubectl_context

Comandos Desabilitados no Modo Não Destrutivo

As seguintes operações destrutivas estão desabilitadas:

  • kubectl_delete: Excluir quaisquer recursos Kubernetes
  • uninstall_helm_chart: Desinstalar charts Helm
  • cleanup: Limpeza de recursos gerenciados
  • cleanup_pods: Limpar pods problemáticos
  • node_management: Operações de gerenciamento de nós (podem drenar nós)
  • kubectl_generic: Acesso geral a comandos kubectl (pode incluir operações destrutivas)

Para recursos avançados adicionais, consulte o ADVANCED_README.md e também a pasta docs para informações específicas sobre helm_install, helm_template_apply, gerenciamento de nós e limpeza de pods.

Arquitetura

Consulte este link DeepWiki para uma visão geral de arquitetura mais aprofundada criada por Devin.

Esta seção descreve a arquitetura de alto nível do servidor MCP Kubernetes.

Fluxo de Solicitação

O diagrama de sequência abaixo ilustra como as solicitações fluem pelo sistema:

sequenceDiagram
    participant Client
    participant Transport as Transport Layer
    participant Server as MCP Server
    participant Filter as Tool Filter
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Note over Transport: StdioTransport or<br>SSE Transport

    Client->>Transport: Send Request
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Filter: Filter available tools
        Note over Filter: Remove destructive tools<br>if in non-destructive mode
        Filter->>Handler: Route to tools handler

        alt kubectl operations
            Handler->>K8sManager: Execute kubectl operation
            K8sManager->>K8s: Make API call
        else Helm operations
            Handler->>K8sManager: Execute Helm operation
            K8sManager->>K8s: Make API call
        else Port Forward operations
            Handler->>K8sManager: Set up port forwarding
            K8sManager->>K8s: Make API call
        end

        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

Consulte este link DeepWiki para uma visão geral de arquitetura mais aprofundada criada por Devin.

Publicando nova versão

Vá para a página de releases, clique em "Draft New Release", clique em "Choose a tag" e crie uma nova tag digitando um novo número de versão usando o formato semver "v{major}.{minor}.{patch}". Em seguida, escreva um título de release "Release v{major}.{minor}.{patch}" e a descrição/changelog se necessário e clique em "Publish Release".

Isso criará uma nova tag que acionará um novo build de release via workflow cd.yml. Após o sucesso, a nova versão será publicada no npm. Observe que não há necessidade de atualizar o package.json manualmente, pois o workflow atualizará automaticamente o número da versão no arquivo package.json e fará um commit para a main.

Não planejado

Adicionar clusters ao kubectx.

Histórico de Estrelas

Star History Chart

🖊️ Citar

Se você achar este repositório útil, por favor cite:

@software{Patel_MCP_Server_Kubernetes_2024,
author = {Patel, Paras and Sonwalkar, Suyog},
month = jul,
title = {{MCP Server Kubernetes}},
url = {https://github.com/Flux159/mcp-server-kubernetes},
version = {2.5.0},
year = {2024}
}