kubeview-mcp

KubeView MCP

Read-only Model Context Protocol server for Kubernetes diagnostics. Agents get two public tools, load schemas on demand, and run multi-step cluster workflows in a single execution pass — so Kubernetes, Helm, Argo Workflows, and Argo CD stay reachable without saturating the context window.

Background: Evicting MCP tool calls from your Kubernetes cluster

How it works

v2 publishes exactly two public tools: run_code and approval-gated kube_pod_exec. Everything else is discovered inside the sandbox via tools.list(), tools.search(), and tools.help() — progressive discovery + programmatic calling.

run_code executes bounded TypeScript with top-level await. One call can list workloads, correlate events, fetch logs, and diff Helm state without shipping intermediate payloads back through the model:

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,
    }),
  })),
);

• Sensitive isolation — kube_pod_exec is unreachable from sandboxed code. Top-level exec requires MCP elicitation, is bound to the argument digest, expires after 10 minutes, and fails closed. kube_port_forward is never a top-level tool and is denied inside code mode by default. tools.disabled() reports which policy blocked a capability and whether that denial is configurable.
• API-driven discovery — Argo Workflows and Argo CD are detected from the Kubernetes API, scoped to the active kube context, cached for 60 s. An unavailable optional API never blocks startup.
• Native reads — resources, metrics, logs, events, and network probes go through the Kubernetes API. Helm releases are parsed from cluster Secrets or ConfigMaps; a local helm binary is a fallback, not a prerequisite.

Quick start

Prerequisites: Node.js ≥ 22 and access to a cluster (KUBECONFIG or in-cluster service account).

npx -y kubeview-mcp

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

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

In Cursor, /kubeview/code-mode injects the typed API into context.

Configuration

Cluster

Variable	Description	Default
KUBECONFIG	Kubeconfig path	~/.kube/config
MCP_KUBE_CONTEXT	Kubernetes context; defaults to the active context	unset
MCP_K8S_SKIP_TLS_VERIFY	Skip TLS verification for the Kubernetes API (true/1)	false
MCP_TIMEOUT	Default operation timeout in ms	plugin default
MCP_HIDE_SENSITIVE	Mask sensitive data globally	false
MCP_DISABLE_KUBERNETES_PLUGIN	Disable the Kubernetes plugin (true/1)	unset
MCP_DISABLE_HELM_PLUGIN	Disable the Helm plugin (true/1)	unset

Mode and capabilities

Variable	Description	Default
MCP_MODE	code (default), all (alias), or tools	code
MCP_CODE_MODE_DISABLED_TOOLS	Comma-separated code-mode denials; empty enables all	JSON/default
MCP_ARGO_TOOLS	Argo override: auto, on, off	auto
MCP_ARGOCD_TOOLS	Argo CD override: auto, on, off	auto
MCP_LOG_LEVEL	error, warn, info, debug	info
KUBE_MCP_FORCE_VM_SANDBOX	Force node:vm in the standalone runtime	unset

HTTP transport

Variable	Description	Default
MCP_TRANSPORT	stdio or http	stdio
MCP_HTTP_HOST / _PORT	HTTP bind (when MCP_TRANSPORT=http)	127.0.0.1:3000
MCP_HTTP_PATH	Streamable HTTP endpoint path	/mcp
MCP_HTTP_JSON_RESPONSE	Prefer JSON over SSE (drops mid-call notifications)	false
MCP_ALLOWED_HOSTS	Host allowlist (required when binding to 0.0.0.0/::)	local defaults
MCP_ALLOWED_ORIGINS	Origin allowlist for HTTP	unset
MCP_APPROVAL_STATE_SECRET	Shared 32+ byte signing secret; required for HTTP approvals	ephemeral (stdio)
MCP_APPROVAL_REPLAY_DIR	Absolute shared-volume directory for one-time HTTP approvals	unset

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 follows the MCP 2026-07-28 stateless core: a fresh server per request, no initialize, no Mcp-Session-Id. Each request carries protocol version, client identity, and capabilities in _meta; modern requests add Mcp-Method/Mcp-Name for gateway routing. 2025-era clients use the SDK's stateless fallback on the same endpoint. State that must survive across calls has to be passed as tool arguments or handles.

HTTP mode refuses to start without both approval variables. Multi-replica deployments need the same secret and a shared writable replay directory; the /tmp example is for a single process only. The published MCP registry entry still targets stdio.

Tool surfaces

MCP_MODE	Exposed tools
unset / code / all	run_code, kube_pod_exec
tools	kube_list, kube_get, kube_logs, helm, kube_pod_exec, plus detected argo and argocd

Domain tools use an operation discriminator:

• helm — list | get | debug
• argo — list | get | logs | cron_list (when Workflow or CronWorkflow is discoverable)
• argocd — list | get | resources | logs | history | status (when Application is discoverable, or with ARGOCD_SERVER + ARGOCD_AUTH_TOKEN)

Discovery is cached per kube context for 60 s. Missing optional APIs are omitted, not fatal.

Code mode

Code mode is the default (MCP_MODE=code). The agent writes short TypeScript against a typed tools global instead of calling dozens of MCP tools.

Inside run_code:

• Typed tools namespaces for Kubernetes, Helm, and any detected Argo capabilities, generated from live schemas so parameters cannot be hallucinated.
• Progressive discovery: tools.list(), tools.search(), tools.help(), and tools.disabled() (the last reports why a capability was blocked).
• A locked-down runtime with only console and tools in scope — no filesystem, no network, no process.

Capability	Inside run_code	Top-level tool
kube_pod_exec	Never available	Requires per-call user approval (10 min, argument-bound)
kube_port_forward	Denied by default (configurable)	Never exposed
Everything else	Available	Only when MCP_MODE=tools

Pod exec approval uses MCP elicitation and fails closed. The standalone npm run code-mode launcher has no trusted approval UI, so it always denies pod exec.

Customizing denials

MCP_CODE_MODE_DISABLED_TOOLS (comma-separated) controls which capabilities are blocked inside run_code. Resolution order:

1. MCP_CODE_MODE_DISABLED_TOOLS env var
2. disabledTools in kube-mcp.code-mode.json
3. Default: ["kube_port_forward"]

An empty env value clears the list. kube_pod_exec cannot be added — it is permanently blocked.

Protocol

MCP 2026-07-28:

• JSON Schema 2020-12 in/out contracts with server-side validation
• Machine-readable structuredContent with text fallback
• Accurate read-only, destructive, idempotent, open-world annotations
• Deterministic tool ordering with cache hints for fixed vs. discovery-dependent surfaces
• Stateless HTTP with discovery and header-based routing (Mcp-Method, Mcp-Name)
• Execution failures returned as tool errors; protocol errors reserved for malformed requests

Local development

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

Protocol tests pin the SDK v2 client to 2026-07-28 and route through the server handler in-process (no open ports):

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

Contributing

Contributions are welcome! Please feel free to submit an issue or a pull request.

License

MIT © mikhae1