kubeview-mcp

KubeView MCP

Servidor de Model Context Protocol somente leitura para diagnósticos de Kubernetes. Em vez de expor dezenas de ferramentas, ele fornece ao agente um runtime TypeScript em sandbox: uma única chamada run_code pode consultar Kubernetes, Helm, Argo Workflows e Argo CD, correlacionar os resultados e retornar apenas a resposta. Payloads intermediários nunca passam pela janela de contexto do modelo. Baseado no padrão execução de código com MCP.

Contexto: Removendo chamadas de ferramentas MCP do seu cluster Kubernetes

Como funciona

A v2 publica exatamente duas ferramentas públicas: run_code e uma kube_pod_exec com gate de aprovação. Todo o resto é descoberto dentro da sandbox via tools.list(), tools.search() e tools.help(), seguindo as diretrizes de descoberta progressiva e chamadas programáticas do MCP.

run_code executa TypeScript limitado com await de nível superior. Uma única chamada pode listar workloads, correlacionar eventos, buscar logs e comparar o estado do Helm sem enviar payloads intermediários de volta pelo modelo:

const pods = await tools.kubernetes.list({ namespace: 'payments' });
const unhealthy = pods.items.filter((p) => p.status?.phase !== 'Running');

return Promise.all(
  unhealthy.map(async (pod) => ({
    pod: pod.metadata?.name,
    logs: await tools.kubernetes.logs({
      namespace: 'payments',
      podName: pod.metadata?.name,
      tailLines: 100,
    }),
  })),
);

• Isolamento sensível — kube_pod_exec é inacessível a partir do código em sandbox. A execução de nível superior exige elicitação MCP, está vinculada ao digest dos argumentos, expira após 10 minutos e falha de forma segura. kube_port_forward nunca é uma ferramenta de nível superior e é negada dentro do modo de código por padrão. tools.disabled() informa qual política bloqueou uma capacidade e se essa negação é configurável.
• Descoberta orientada por API — Argo Workflows e Argo CD são detectados a partir da API Kubernetes, com escopo no contexto kube ativo, com cache de 60 s. Uma API opcional indisponível nunca bloqueia a inicialização.
• Leituras nativas — recursos, métricas, logs, eventos e sondas de rede passam pela API Kubernetes. Releases do Helm são analisados a partir de Secrets ou ConfigMaps do cluster; um binário helm local é um fallback, não um pré-requisito.

Início rápido

Pré-requisitos: Node.js ≥ 22 e acesso a um cluster (KUBECONFIG ou conta de serviço no cluster).

npx -y kubeview-mcp

# Claude Code
claude mcp add kubernetes -- npx kubeview-mcp

{
  "mcpServers": {
    "kubeview": {
      "command": "npx",
      "args": ["-y", "kubeview-mcp"]
    }
  }
}

No Cursor, /kubeview/code-mode injeta a API tipada no contexto.

Configuração

Cluster

Variável	Descrição	Padrão
KUBECONFIG	Caminho do kubeconfig	~/.kube/config
MCP_KUBE_CONTEXT	Contexto Kubernetes; usa o contexto ativo por padrão	não definido
MCP_K8S_SKIP_TLS_VERIFY	Ignorar verificação TLS para a API Kubernetes (true/1)	false
MCP_TIMEOUT	Timeout padrão de operação em ms	padrão do plugin
MCP_HIDE_SENSITIVE	Mascarar dados sensíveis globalmente	false
MCP_DISABLE_KUBERNETES_PLUGIN	Desabilitar o plugin Kubernetes (true/1)	não definido
MCP_DISABLE_HELM_PLUGIN	Desabilitar o plugin Helm (true/1)	não definido

Modo e capacidades

Variável	Descrição	Padrão
MCP_MODE	code (padrão), all (alias) ou tools	code
MCP_CODE_MODE_DISABLED_TOOLS	Negações do modo de código separadas por vírgula; vazio habilita tudo	JSON/padrão
MCP_ARGO_TOOLS	Override do Argo: auto, on, off	auto
MCP_ARGOCD_TOOLS	Override do Argo CD: auto, on, off	auto
MCP_LOG_LEVEL	error, warn, info, debug	info
KUBE_MCP_FORCE_VM_SANDBOX	Forçar node:vm no runtime autônomo	não definido

Transporte HTTP

Variável	Descrição	Padrão
MCP_TRANSPORT	stdio ou http	stdio
MCP_HTTP_HOST / _PORT	Bind HTTP (quando MCP_TRANSPORT=http)	127.0.0.1:3000
MCP_HTTP_PATH	Caminho do endpoint HTTP streamable	/mcp
MCP_HTTP_JSON_RESPONSE	Preferir JSON em vez de SSE (descarta notificações no meio da chamada)	false
MCP_ALLOWED_HOSTS	Allowlist de hosts (obrigatório ao fazer bind em 0.0.0.0/::)	padrões locais
MCP_ALLOWED_ORIGINS	Allowlist de origens para HTTP	não definido
MCP_APPROVAL_STATE_SECRET	Segredo de assinatura compartilhado de 32+ bytes; obrigatório para aprovações HTTP	efêmero (stdio)
MCP_APPROVAL_REPLAY_DIR	Diretório absoluto de volume compartilhado para aprovações HTTP únicas	não definido

mkdir -p /tmp/kubeview-mcp-approvals
MCP_APPROVAL_STATE_SECRET='replace-with-at-least-32-random-bytes' \
MCP_APPROVAL_REPLAY_DIR=/tmp/kubeview-mcp-approvals \
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 npx -y kubeview-mcp

Endpoint: http://127.0.0.1:3000/mcp. HTTP segue o núcleo stateless MCP 2026-07-28: um servidor novo por requisição, sem initialize, sem Mcp-Session-Id. Cada requisição carrega versão do protocolo, identidade do cliente e capacidades em _meta; requisições modernas adicionam Mcp-Method/Mcp-Name para roteamento por gateway. Clientes da era 2025 usam o fallback stateless do SDK no mesmo endpoint. Estado que precisa sobreviver entre chamadas deve ser passado como argumentos de ferramenta ou handles.

O modo HTTP se recusa a iniciar sem ambas as variáveis de aprovação. Implantações com múltiplas réplicas precisam do mesmo segredo e de um diretório de replay compartilhado gravável; o exemplo /tmp é apenas para um único processo. A entrada publicada no registro MCP ainda tem como alvo stdio.

Superfícies de ferramentas

MCP_MODE	Ferramentas expostas
não definido / code / all	run_code, kube_pod_exec
tools	kube_list, kube_get, kube_logs, helm, kube_pod_exec, além de argo e argocd detectados

Ferramentas de domínio usam um discriminador operation:

• helm — list | get | debug
• argo — list | get | logs | cron_list (quando Workflow ou CronWorkflow é detectável)
• argocd — list | get | resources | logs | history | status (quando Application é detectável, ou com ARGOCD_SERVER + ARGOCD_AUTH_TOKEN)

A descoberta é armazenada em cache por contexto kube por 60 s. APIs opcionais ausentes são omitidas, não fatais.

Modo de código

O modo de código é o padrão (MCP_MODE=code). O agente escreve TypeScript curto contra um global tools tipado em vez de chamar dezenas de ferramentas MCP.

Dentro de run_code:

• Namespaces tools tipados para Kubernetes, Helm e quaisquer capacidades Argo detectadas, gerados a partir de schemas ao vivo para que parâmetros não possam ser alucinados.
• Descoberta progressiva: tools.list(), tools.search(), tools.help() e tools.disabled() (o último informa por que uma capacidade foi bloqueada).
• Um runtime bloqueado com apenas console e tools no escopo — sem filesystem, sem rede, sem process.

Capacidade	Dentro de run_code	Ferramenta de nível superior
kube_pod_exec	Nunca disponível	Exige aprovação do usuário por chamada (10 min, vinculada a argumentos)
kube_port_forward	Negada por padrão (configurável)	Nunca exposta
Todo o resto	Disponível	Apenas quando MCP_MODE=tools

A aprovação de pod exec usa elicitação MCP e falha de forma segura. O launcher autônomo npm run code-mode não tem UI de aprovação confiável, então sempre nega pod exec.

Personalizando negações

MCP_CODE_MODE_DISABLED_TOOLS (separado por vírgulas) controla quais capacidades são bloqueadas dentro de run_code. Ordem de resolução:

1. Variável de ambiente MCP_CODE_MODE_DISABLED_TOOLS
2. disabledTools em kube-mcp.code-mode.json
3. Padrão: ["kube_port_forward"]

Um valor de ambiente vazio limpa a lista. kube_pod_exec não pode ser adicionado — está permanentemente bloqueado.

Protocolo

MCP 2026-07-28:

• Contratos de entrada/saída JSON Schema 2020-12 com validação no lado do servidor
• structuredContent legível por máquina com fallback de texto
• Anotações precisas de read-only, destructive, idempotent, open-world
• Ordenação determinística de ferramentas com dicas de cache para superfícies fixas vs. dependentes de descoberta
• HTTP stateless com descoberta e roteamento baseado em cabeçalhos (Mcp-Method, Mcp-Name)
• Falhas de execução retornadas como erros de ferramenta; erros de protocolo reservados para requisições malformadas

Desenvolvimento local

git clone https://github.com/mikhae1/kubeview-mcp.git
cd kubeview-mcp && npm install

npm run build      # compile
npm start          # build + run
npm test           # jest suite
npm run typecheck  # tsc --noEmit

# Invoke a tool directly
npm run command -- kube_list --namespace=default

Testes de protocolo fixam o cliente SDK v2 em 2026-07-28 e roteiam pelo handler do servidor em processo (sem portas abertas):

npm test -- --runInBand \
  tests/server/StreamableHttpTransport.integration.test.ts \
  tests/server/StreamableHttpRuntime.test.ts \
  tests/server/TransportConfig.test.ts \
  tests/compat/McpSdkCompatibility.test.ts

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir uma issue ou um pull request.

Licença

MIT © mikhae1