Kubernetes Server

mcp-kubernetes-server

O mcp-kubernetes-server é um servidor que implementa o Model Context Protocol (MCP) para permitir que assistentes de IA (como Claude, Cursor e GitHub Copilot) interajam com clusters Kubernetes. Ele atua como uma ponte, traduzindo solicitações em linguagem natural desses assistentes em operações Kubernetes e retornando os resultados.

Ele permite que assistentes de IA:

• Consultar recursos Kubernetes
• Executar comandos kubectl
• Gerenciar clusters Kubernetes por meio de interações em linguagem natural
• Diagnosticar e interpretar os estados dos recursos Kubernetes

Como Funciona

O mcp-kubernetes-server atua como intermediário entre assistentes de IA (que suportam o Model Context Protocol) e seu cluster Kubernetes. Ele recebe solicitações em linguagem natural desses assistentes, traduz-as em comandos kubectl ou chamadas diretas à API Kubernetes e as executa no cluster de destino. O servidor então processa os resultados e retorna uma resposta estruturada, permitindo interação perfeita com seu ambiente Kubernetes por meio do assistente de IA.

Como Instalar

Pré-requisitos

Antes de instalar o mcp-kubernetes-server, certifique-se de ter o seguinte:

• Um cluster Kubernetes em funcionamento.
• Um arquivo kubeconfig configurado corretamente para acessar seu cluster Kubernetes (o servidor requer este arquivo para interação).
• A ferramenta de linha de comando kubectl instalada e no PATH do seu sistema (usada pelo servidor para executar muitos comandos Kubernetes).
• A ferramenta de linha de comando helm instalada e no PATH do seu sistema (usada pelo servidor para operações de chart Helm).
• Python >= 3.11, se você planeja instalar e executar o servidor diretamente usando uvx (sem Docker).

Docker

Obtenha seu arquivo kubeconfig para seu cluster Kubernetes e configure no mcpServers (substitua o caminho src pelo caminho do seu kubeconfig):

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/home/username/.kube/config,dst=/home/mcp/.kube/config",
        "ghcr.io/feiskyer/mcp-kubernetes-server"
      ]
    }
  }
}

UVX

Para executar o servidor usando uvx (uma ferramenta incluída com uv, o empacotador Python), primeiro certifique-se de que uv esteja instalado:

# For Linux and MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# 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 em Claude Desktop, Cursor, ChatGPT Copilot, Github Copilot e outros clientes de IA suportados, por exemplo,

{
  "mcpServers": {
    "kubernetes": {
      "command": "uvx",
      "args": [
        "mcp-kubernetes-server"
      ],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

Opções do Servidor MCP

usage: main.py [-h] [--disable-kubectl] [--disable-helm] [--disable-write]
               [--disable-delete] [--transport {stdio,sse,streamable-http}]
               [--host HOST] [--port PORT]

MCP Kubernetes Server

options:
  -h, --help            show this help message and exit
  --disable-kubectl     Disable kubectl command execution
  --disable-helm        Disable helm command execution
  --disable-write       Disable write operations
  --disable-delete      Disable delete operations
  --transport {stdio,sse,streamable-http}
                        Transport mechanism to use (stdio or sse or streamable-http)
  --host HOST           Host to use for sse or streamable-http server
  --port PORT           Port to use for sse or streamable-http server

Uso

Depois que o mcp-kubernetes-server estiver instalado e configurado no seu cliente de IA (usando os trechos JSON fornecidos na seção 'Como instalar' para Docker ou UVX), você pode começar a interagir com seu cluster Kubernetes por meio de linguagem natural. Por exemplo, você pode perguntar:

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Verificando o servidor: Se você estiver executando o servidor com transporte stdio (comum para execução direta de uvx), o cliente de IA normalmente iniciará e gerenciará o processo do servidor. Para transportes sse ou streamable-http, o servidor é executado de forma independente. Você o teria iniciado manualmente (por exemplo, uvx mcp-kubernetes-server --transport sse) e deveria ver uma saída no seu terminal indicando que está em execução (por exemplo, INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)). Você também pode verificar se há mensagens de erro no terminal do servidor se o cliente de IA falhar ao conectar.

Ferramentas Disponíveis

O mcp-kubernetes-server fornece um conjunto abrangente de ferramentas para interagir com clusters Kubernetes, categorizadas por tipo de operação:

Desenvolvimento

Como executar o projeto localmente:

uv run -m src.mcp_kubernetes_server.main

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

npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main

Solução de Problemas

Aqui estão alguns problemas comuns e suas soluções ao trabalhar com mcp-kubernetes-server:

Problema: mcp-kubernetes-server não consegue se conectar ao cluster Kubernetes ou relata erros de autenticação. Solução:

• Garanta que o arquivo kubeconfig esteja configurado corretamente e aponte para o cluster desejado.
• Verifique se o caminho para o arquivo kubeconfig está especificado corretamente na configuração do mcpServers (para Docker, garanta que o caminho de montagem esteja correto; para uvx, garanta que a variável de ambiente KUBECONFIG esteja definida corretamente).
• Verifique se as credenciais no seu kubeconfig têm as permissões necessárias para realizar operações no cluster. Você pode testar isso com kubectl diretamente (por exemplo, kubectl get pods).

Problema: os comandos kubectl ou helm retornam um erro como "command not found" ou estão desabilitados. Solução:

• Se estiver executando via uvx, garanta que kubectl e/ou helm estejam instalados no seu sistema e disponíveis no seu PATH. Consulte a seção "Pré-requisitos" para orientações de instalação.
• Se você vir uma mensagem como "Write operations are not allowed" ou "Delete operations are not allowed", o servidor pode ter sido iniciado com flags como --disable-kubectl, --disable-helm, --disable-write ou --disable-delete. Verifique o comando de inicialização do servidor e a seção "Opções do Servidor MCP" no README para detalhes sobre essas flags.

Problema: Como posso ver as solicitações e respostas brutas entre meu cliente de IA e o mcp-kubernetes-server? Solução:

• Você pode usar a ferramenta @modelcontextprotocol/inspector conforme mencionado na seção "Desenvolvimento": npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main. Isso mostrará as mensagens MCP sendo trocadas.

Problema: O servidor inicia, mas o cliente de IA não consegue se conectar. Solução:

• Se estiver usando o transporte stdio (padrão para execução direta do uvx), garanta que seu cliente de IA esteja configurado para iniciar o comando mcp-kubernetes-server corretamente.
• Se estiver usando o transporte sse ou streamable-http, garanta que o host e a porta configurados no mcp-kubernetes-server (por exemplo, --host 0.0.0.0 --port 8000) sejam acessíveis de onde seu cliente de IA está sendo executado. Verifique regras de firewall ou problemas de configuração de rede. Além disso, verifique se o cliente de IA está configurado com a URL correta para o servidor.

Contribuição

Este projeto é open source, disponível no GitHub em feiskyer/mcp-kubernetes-server e licenciado sob a Apache License.

Se você gostaria de contribuir com o projeto, siga estas diretrizes:

1. Faça um fork do repositório e clone-o para sua máquina local.
2. Crie um novo branch para suas alterações.
3. Faça suas alterações e faça commit delas com uma mensagem de commit descritiva.
4. Envie suas alterações para o repositório forkado.
5. Abra um pull request para o repositório principal.

LICENÇA

O projeto é licenciado sob a Apache License 2.0. Consulte o arquivo LICENSE para mais detalhes.