Kubernetes MCP

k8s-mcp

Um servidor Model Context Protocol (MCP) baseado em Python, somente leitura, para clusters Kubernetes, que expõe uma API abrangente para recuperar informações do cluster e diagnosticar problemas.

Exemplo de chat usando Claude

Instalação

Pré-requisitos

• Python 3.8+
• Acesso a um cluster Kubernetes (via kubeconfig ou configuração in-cluster)
• Pacotes Python necessários (veja dependencies em pyproject.toml)
• uv - https://github.com/astral-sh/uv

# To install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone git@github.com:vlttnv/k8s-mcp.git
cd k8s-mcp

# Install dependencies
uv venv
source .venv/bin/activate
uv sync

Se estiver usando Claude, configure abrindo a configuração do Claude for Desktop App em ~/Library/Application Support/Claude/claude_desktop_config.json em um editor de texto. Certifique-se de criar o arquivo se ele não existir.

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "k8s-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
                "run",
                "server.py"
            ]
        }
    }
}

Talvez seja necessário colocar o caminho completo para o executável uv no campo de comando. Você pode obtê-lo executando which uv no MacOS/Linux ou where uv no Windows.

Configuração

O aplicativo tenta automaticamente dois métodos para conectar ao seu cluster Kubernetes:

1. Arquivo Kubeconfig: Usa seu arquivo kubeconfig local (normalmente localizado em ~/.kube/config)
2. Configuração In-Cluster: Se estiver rodando dentro de um pod Kubernetes, usa o token da conta de serviço

Nenhuma configuração adicional é necessária se o seu kubeconfig estiver configurado corretamente ou se você estiver rodando dentro de um cluster com permissões RBAC apropriadas.

Uso

Exemplos

Aqui estão alguns exemplos de prompts úteis que você pode perguntar ao Claude sobre seu cluster Kubernetes e seus recursos:

Status Geral do Cluster

• "Qual é a saúde geral do meu cluster?"
• "Mostre-me todos os namespaces no meu cluster"
• "Quais nós estão disponíveis no meu cluster e qual é o status deles?"
• "Como está a utilização de recursos nos meus nós?"

Pods e Deployments

• "Liste todos os pods no namespace de produção"
• "Existem pods no estado CrashLoopBackOff?"
• "Mostre-me pods com altas contagens de reinicialização"
• "Liste todos os deployments em todos os namespaces"
• "Quais deployments estão falhando em progredir?"

Depuração de Problemas

• "Por que meu pod no namespace de staging está falhando?"
• "Obtenha a configuração YAML para o serviço no namespace de produção"
• "Mostre-me eventos recentes no namespace padrão"
• "Existem pods presos no estado Pending?"
• "O que está causando erros ImagePullBackOff no meu cluster?"

Gerenciamento de Recursos

• "Mostre-me o consumo de recursos dos nós no meu cluster"
• "Existem recursos órfãos que devo limpar?"
• "Liste todos os serviços no namespace de produção"
• "Compare as solicitações de recursos entre staging e produção"

Inspeção de Recursos Específicos

• "Mostre-me a configuração do deployment coredns no kube-system"
• "Obtenha detalhes do serviço reverse-proxy no staging"
• "Quais contêineres estão rodando no pod xyz?"
• "Mostre-me os logs do pod com falha"

Referência da API

Namespaces

• get_namespaces(): Lista todos os namespaces disponíveis no cluster

Pods

• list_pods(namespace=None): Lista todos os pods, opcionalmente filtrados por namespace
• failed_pods(): Lista todos os pods no estado Failed ou Error
• pending_pods(): Lista todos os pods no estado Pending com motivos
• high_restart_pods(restart_threshold=5): Encontra pods com contagens de reinicialização acima do limite

Nodes

• list_nodes(): Lista todos os nós e seus status
• node_capacity(): Mostra a capacidade disponível em todos os nós

Deployments e Serviços

• list_deployments(namespace=None): Lista todos os deployments
• list_services(namespace=None): Lista todos os serviços
• list_events(namespace=None): Lista todos os eventos

Gerenciamento de Recursos

• orphaned_resources(): Lista recursos sem referências de proprietário
• get_resource_yaml(namespace, resource_type, resource_name): Obtém a configuração YAML para um recurso específico

Licença

Licença MIT

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.