mcp-kubernetes

mcp-kubernetes

Um servidor Model Context Protocol para Kubernetes. Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, etc.) inspecione e opere clusters Kubernetes em múltiplos contextos — com o comportamento controlado inteiramente por flags.

O objetivo do design é seguro por padrão: ele inicia somente leitura, pode ser limitado a uma lista de permissões de namespaces e contextos, protege namespaces do sistema contra mutação e condiciona as operações perigosas (delete, apply, exec) a opt-ins explícitos.

Recursos

• Multi-cluster — cada ferramenta aceita um context opcional; limite quais contextos são utilizáveis com uma lista de permissões.
• Modos de acesso — read-only → read-write → admin, em camadas, de modo que um modo nunca expõe ferramentas acima do seu nível.
• Flags de segurança — lista de permissões de namespaces, namespaces protegidos, lista de permissões de contextos, além de opt-ins independentes para delete / apply / exec, dry-run e registro de auditoria em JSON (veja abaixo).
• Autenticação padrão — usa seu kube-config (ou service account no cluster). Nenhuma credencial é armazenada pelo servidor.

Modelo de segurança

Preocupação	Flag	Padrão	Efeito
O que o servidor pode fazer?	K8S_MODE	read-only	read-only expõe apenas leituras; read-write adiciona mutações; admin adiciona ferramentas destrutivas. Ferramentas acima do modo nunca são registradas.
Quais namespaces estão no escopo?	K8S_NAMESPACE_ALLOWLIST	(todos)	Quando definido, qualquer operação em um namespace fora da lista é recusada.
Quais namespaces são somente leitura para sempre?	K8S_PROTECTED_NAMESPACES	kube-system,kube-public,kube-node-lease	Podem ser lidos, mas nunca mutados ou excluídos, independentemente do modo.
Quais clusters são acessíveis?	K8S_CONTEXT_ALLOWLIST	(todos)	Quando definido, apenas esses contextos do kube-config podem ser alvo.
Pode excluir?	K8S_ALLOW_DELETE	false	delete_resource precisa disso e do modo admin.
Pode aplicar manifests?	K8S_ALLOW_APPLY	false	apply_manifest precisa disso e do modo leitura-escrita.
Pode executar comandos em pods?	K8S_ALLOW_EXEC	false	exec_in_pod precisa disso e do modo admin; a ferramenta nem é registrada caso contrário.
Pré-visualizar sem tocar no cluster	K8S_DRY_RUN	false	Ferramentas de escrita/admin validam e registram a intenção, depois retornam sem chamar a API.
Trilha de auditoria	K8S_AUDIT_LOG	true	Emite uma linha JSON para stderr por operação protegida (ALLOW / DENY / DRY_RUN).

As camadas são independentes — por exemplo, o modo admin com todos os três opt-ins false pode reiniciar e escalar deployments, mas não pode excluir recursos nem executar comandos em pods.

Ferramentas

Leitura (read-only+): list_contexts, list_namespaces, list_pods, get_pod, get_pod_logs, list_deployments, list_services, list_nodes, list_events, get_resource

Escrita (read-write+): scale_deployment, restart_deployment, set_deployment_image, create_namespace, apply_manifest (precisa de K8S_ALLOW_APPLY)

Admin (admin): delete_resource (precisa de K8S_ALLOW_DELETE), exec_in_pod (precisa de K8S_ALLOW_EXEC)

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-kubernetes. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para todas as variáveis e docs/CLIENTS.md para o guia completo por cliente.

Claude Code (CLI)

claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetes

Claude Desktop · Cursor · Windsurf — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — em ~/.codex/config.toml:

[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agent) — em .vscode/mcp.json:

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desenvolvimento

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

Publicação

Este servidor inclui um server.json para o registro oficial do MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md para publicar no npm e listar no registro do MCP, Smithery, Glama, Cursor e PulseMCP.

Licença

MIT