{
  "markdown": "# KubeView MCP\n\n[![npm version](https://img.shields.io/npm/v/kubeview-mcp)](https://www.npmjs.com/package/kubeview-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-2026--07--28-0ea5e9)](https://modelcontextprotocol.io/specification/2026-07-28)\n\nRead-only [Model Context Protocol](https://modelcontextprotocol.io/) server for Kubernetes diagnostics. Instead of exposing dozens of tools, it gives the agent a sandboxed TypeScript runtime: a single `run_code` call can query Kubernetes, Helm, Argo Workflows, and Argo CD, correlate the results, and return only the answer. Intermediate payloads never pass through the model's context window. Based on the [code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) pattern.\n\n> Background: [Evicting MCP tool calls from your Kubernetes cluster](https://dev.to/mikhae1/evicting-mcp-tool-calls-from-your-kubernetes-cluster-428k)\n\n## How it works\n\nv2 publishes exactly two public tools: `run_code` and an approval-gated `kube_pod_exec`. Everything else is discovered inside the sandbox via `tools.list()`, `tools.search()`, and `tools.help()`, following the MCP [progressive discovery and programmatic calling](https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices) guidance.\n\n`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:\n\n```ts\nconst pods = await tools.kubernetes.list({ namespace: 'payments' });\nconst unhealthy = pods.items.filter((p) => p.status?.phase !== 'Running');\n\nreturn Promise.all(\n  unhealthy.map(async (pod) => ({\n    pod: pod.metadata?.name,\n    logs: await tools.kubernetes.logs({\n      namespace: 'payments',\n      podName: pod.metadata?.name,\n      tailLines: 100,\n    }),\n  })),\n);\n```\n\n- **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.\n- **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.\n- **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.\n\n## Quick start\n\n**Prerequisites:** Node.js ≥ 22 and access to a cluster (`KUBECONFIG` or in-cluster service account).\n\n```bash\nnpx -y kubeview-mcp\n\n# Claude Code\nclaude mcp add kubernetes -- npx kubeview-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"kubeview\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kubeview-mcp\"]\n    }\n  }\n}\n```\n\nIn Cursor, `/kubeview/code-mode` injects the typed API into context.\n\n## Configuration\n\n### Cluster\n\n| Variable                        | Description                                               | Default          |\n| ------------------------------- | --------------------------------------------------------- | ---------------- |\n| `KUBECONFIG`                    | Kubeconfig path                                           | `~/.kube/config` |\n| `MCP_KUBE_CONTEXT`              | Kubernetes context; defaults to the active context        | unset            |\n| `MCP_K8S_SKIP_TLS_VERIFY`       | Skip TLS verification for the Kubernetes API (`true`/`1`) | `false`          |\n| `MCP_TIMEOUT`                   | Default operation timeout in ms                           | plugin default   |\n| `MCP_HIDE_SENSITIVE`            | Mask sensitive data globally                              | `false`          |\n| `MCP_DISABLE_KUBERNETES_PLUGIN` | Disable the Kubernetes plugin (`true`/`1`)                | unset            |\n| `MCP_DISABLE_HELM_PLUGIN`       | Disable the Helm plugin (`true`/`1`)                      | unset            |\n\n### Mode and capabilities\n\n| Variable                       | Description                                          | Default      |\n| ------------------------------ | ---------------------------------------------------- | ------------ |\n| `MCP_MODE`                     | `code` (default), `all` (alias), or `tools`          | `code`       |\n| `MCP_CODE_MODE_DISABLED_TOOLS` | Comma-separated code-mode denials; empty enables all | JSON/default |\n| `MCP_ARGO_TOOLS`               | Argo override: `auto`, `on`, `off`                   | `auto`       |\n| `MCP_ARGOCD_TOOLS`             | Argo CD override: `auto`, `on`, `off`                | `auto`       |\n| `MCP_LOG_LEVEL`                | `error`, `warn`, `info`, `debug`                     | `info`       |\n| `KUBE_MCP_FORCE_VM_SANDBOX`    | Force `node:vm` in the standalone runtime            | unset        |\n\n### HTTP transport\n\n| Variable                    | Description                                                 | Default           |\n| --------------------------- | ----------------------------------------------------------- | ----------------- |\n| `MCP_TRANSPORT`             | `stdio` or `http`                                           | `stdio`           |\n| `MCP_HTTP_HOST` / `_PORT`   | HTTP bind (when `MCP_TRANSPORT=http`)                       | `127.0.0.1:3000`  |\n| `MCP_HTTP_PATH`             | Streamable HTTP endpoint path                               | `/mcp`            |\n| `MCP_HTTP_JSON_RESPONSE`    | Prefer JSON over SSE (drops mid-call notifications)         | `false`           |\n| `MCP_ALLOWED_HOSTS`         | Host allowlist (required when binding to `0.0.0.0`/`::`)    | local defaults    |\n| `MCP_ALLOWED_ORIGINS`       | Origin allowlist for HTTP                                   | unset             |\n| `MCP_APPROVAL_STATE_SECRET` | Shared 32+ byte signing secret; required for HTTP approvals | ephemeral (stdio) |\n| `MCP_APPROVAL_REPLAY_DIR`   | Absolute shared-volume directory for one-time HTTP approvals | unset             |\n\n```bash\nmkdir -p /tmp/kubeview-mcp-approvals\nMCP_APPROVAL_STATE_SECRET='replace-with-at-least-32-random-bytes' \\\nMCP_APPROVAL_REPLAY_DIR=/tmp/kubeview-mcp-approvals \\\nMCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 npx -y kubeview-mcp\n```\n\nEndpoint: `http://127.0.0.1:3000/mcp`. HTTP follows the [MCP 2026-07-28 stateless core](https://blog.modelcontextprotocol.io/posts/2026-07-28/): 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.\n\nHTTP 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`.\n\n## Tool surfaces\n\n| `MCP_MODE`             | Exposed tools                                                                                    |\n| ---------------------- | ------------------------------------------------------------------------------------------------ |\n| unset / `code` / `all` | `run_code`, `kube_pod_exec`                                                                      |\n| `tools`                | `kube_list`, `kube_get`, `kube_logs`, `helm`, `kube_pod_exec`, plus detected `argo` and `argocd` |\n\nDomain tools use an `operation` discriminator:\n\n- `helm` — `list` \\| `get` \\| `debug`\n- `argo` — `list` \\| `get` \\| `logs` \\| `cron_list` (when `Workflow` or `CronWorkflow` is discoverable)\n- `argocd` — `list` \\| `get` \\| `resources` \\| `logs` \\| `history` \\| `status` (when `Application` is discoverable, or with `ARGOCD_SERVER` + `ARGOCD_AUTH_TOKEN`)\n\nDiscovery is cached per kube context for 60 s. Missing optional APIs are omitted, not fatal.\n\n## Code mode\n\nCode mode is the default (`MCP_MODE=code`). The agent writes short TypeScript against a typed `tools` global instead of calling dozens of MCP tools.\n\nInside `run_code`:\n\n- Typed `tools` namespaces for Kubernetes, Helm, and any detected Argo capabilities, generated from live schemas so parameters cannot be hallucinated.\n- Progressive discovery: `tools.list()`, `tools.search()`, `tools.help()`, and `tools.disabled()` (the last reports *why* a capability was blocked).\n- A locked-down runtime with only `console` and `tools` in scope — no filesystem, no network, no `process`.\n\n| Capability          | Inside `run_code`                | Top-level tool                                           |\n| ------------------- | -------------------------------- | -------------------------------------------------------- |\n| `kube_pod_exec`     | Never available                  | Requires per-call user approval (10 min, argument-bound) |\n| `kube_port_forward` | Denied by default (configurable) | Never exposed                                            |\n| Everything else     | Available                        | Only when `MCP_MODE=tools`                               |\n\nPod 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.\n\n### Customizing denials\n\n`MCP_CODE_MODE_DISABLED_TOOLS` (comma-separated) controls which capabilities are blocked inside `run_code`. Resolution order:\n\n1. `MCP_CODE_MODE_DISABLED_TOOLS` env var\n2. `disabledTools` in `kube-mcp.code-mode.json`\n3. Default: `[\"kube_port_forward\"]`\n\nAn empty env value clears the list. `kube_pod_exec` cannot be added — it is permanently blocked.\n\n## Protocol\n\nMCP 2026-07-28:\n\n- JSON Schema 2020-12 in/out contracts with server-side validation\n- Machine-readable `structuredContent` with text fallback\n- Accurate `read-only`, `destructive`, `idempotent`, `open-world` annotations\n- Deterministic tool ordering with cache hints for fixed vs. discovery-dependent surfaces\n- Stateless HTTP with discovery and header-based routing (`Mcp-Method`, `Mcp-Name`)\n- Execution failures returned as tool errors; protocol errors reserved for malformed requests\n\n## Local development\n\n```bash\ngit clone https://github.com/mikhae1/kubeview-mcp.git\ncd kubeview-mcp && npm install\n\nnpm run build      # compile\nnpm start          # build + run\nnpm test           # jest suite\nnpm run typecheck  # tsc --noEmit\n\n# Invoke a tool directly\nnpm run command -- kube_list --namespace=default\n```\n\nProtocol tests pin the SDK v2 client to `2026-07-28` and route through the server handler in-process (no open ports):\n\n```bash\nnpm test -- --runInBand \\\n  tests/server/StreamableHttpTransport.integration.test.ts \\\n  tests/server/StreamableHttpRuntime.test.ts \\\n  tests/server/TransportConfig.test.ts \\\n  tests/compat/McpSdkCompatibility.test.ts\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit an issue or a pull request.\n\n## License\n\nMIT © [mikhae1](https://github.com/mikhae1/kubeview-mcp)\n",
  "bytes": 11440,
  "sha": "60a9f1d16bda18a73f9e69c08c8e70c2047c0e7268a63cb58aaa00dc688f1575",
  "repo_slug": "mikhae1/kubeview-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mikhae1_kubeview_fcf041a9/readme"
}