io.github.mikhae1/kubeview

Official

by mikhae1 · TypeScript

Read-only Model Context Protocol MCP server enabling code-driven AI analysis of Kubernetes clusters.

Read-only analysis of Kubernetes clusters for AI-driven code inspection.

Topics

ai-toolsargodevopsdiagnosticshelmkubectlkubernetesmcpmcp-servercode-modecode-mode-mcpmcp-code-executionai-agentskubernetes-toolsllm-tools

README.md8 KBView on GitHub

KubeView MCP – Kubernetes Model Context Protocol Server

KubeView is a read-only Model Context Protocol (MCP) server that lets AI agents (Cursor, Claude Code, Codex CLI, Gemini CLI, etc.) safely inspect, diagnose, and debug Kubernetes clusters. It covers Kubernetes core, Helm, Argo Workflows, and Argo CD.

Read more: Evicting MCP tool calls from your Kubernetes cluster

✨ Features

🧠 Code Mode – Sandboxed TypeScript runtime for complex reasoning and multi-step workflows.
🛡️ Read-Only & Safe – Zero write access; sensitive data masking for production clusters.
☸️ Kubernetes – List/get resources, fetch metrics, stream logs and events, exec into containers, diagnose network issues.
📦 Helm (API-first) – Inspect releases, values, manifests, and history via the Kubernetes API with CLI fallback.
🐙 Argo Ecosystem – Manage Argo Workflows and Argo CD via the Kubernetes API or CLI.

🚀 Quick Start

Prerequisites

Node.js ≥ 18
Access to a Kubernetes cluster
Optional CLIs in $PATH: helm (fallback only), argo, argocd

Installation

bash

# Run the server directly
npx -y kubeview-mcp

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

MCP Client Configuration

Add to your mcpServers config (Cursor, Claude Desktop, etc.):

json

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

Environment Variables

Variable	Description	Default
`KUBECONFIG`	Path to kubeconfig file	`~/.kube/config`
`MCP_TRANSPORT`	Transport: `stdio` (default) or `http`	`stdio`
`MCP_MODE`	Server mode: `all`, `code`, or `tools`	`all`
`MCP_LOG_LEVEL`	Log level: `error`, `warn`, `info`, `debug`	`info`
`MCP_HIDE_SENSITIVE`	Mask sensitive data globally	`false`
`MCP_HTTP_HOST`	HTTP bind host when `MCP_TRANSPORT=http`	`127.0.0.1`
`MCP_HTTP_PORT`	HTTP port when `MCP_TRANSPORT=http`	`3000`
`MCP_HTTP_PATH`	Streamable HTTP endpoint path	`/mcp`
`MCP_HTTP_STATELESS`	Disable session IDs in HTTP mode	`false`
`MCP_HTTP_JSON_RESPONSE`	Prefer JSON responses over SSE	`false`
`MCP_ALLOWED_HOSTS`	Comma-separated Host allowlist for HTTP mode	local defaults
`MCP_ALLOWED_ORIGINS`	Comma-separated Origin allowlist for HTTP mode	unset

Streamable HTTP Mode

KubeView can also run as a standalone Streamable HTTP server for hosted or manually managed deployments.

bash

MCP_TRANSPORT=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3000 \
npx -y kubeview-mcp

This starts a Streamable HTTP endpoint at http://127.0.0.1:3000/mcp.

Notes:

stdio remains the default and is still the right choice for MCP client configs such as Claude Desktop, Cursor, and Codex CLI.
MCP_HTTP_STATELESS=true disables session IDs. That is useful for simple request/response patterns, but stateful features such as plan_step history are not meaningful in that mode.
If you bind HTTP mode to 0.0.0.0 or ::, you must set MCP_ALLOWED_HOSTS.
HTTP mode is intended for manual deployment. The published MCP registry metadata still targets stdio.

🛠️ Tools

Kubernetes

Tool	Description
`kube_list`	List resources or get cluster diagnostics
`kube_get`	Describe a specific resource (all K8s types supported)
`kube_metrics`	Fetch CPU/memory metrics for nodes and pods
`kube_logs`	Fetch or stream container logs
`kube_exec`	Execute commands inside containers
`kube_port`	Port-forward to pods or services
`kube_net`	Run in-cluster network diagnostics

Helm

Tool	Description
`helm_list`	List Helm releases (Kubernetes API first, CLI fallback)
`helm_get`	Fetch release values, manifests, notes, hooks, status, history

Helm execution strategy: Tools read Helm metadata directly from Kubernetes storage (Secrets / ConfigMaps) by default — no helm binary needed for standard read-only use. CLI fallback is used for non-JSON formatting or non-Kubernetes storage backends (e.g. SQL).

Argo

Tool	Description
`argo_list`	List Argo Workflows
`argo_get`	Inspect a specific Argo Workflow
`argocd_app`	Inspect Argo CD applications

Utilities

Tool	Description
`run_code`	Execute sandboxed TypeScript for complex tasks
`plan_step`	Persist step-by-step planning state across long investigations

Why plan_step? It keeps the chat context clean by storing progress externally, gives agents a structured state machine (plan → execute → verify → branch), and encourages the think-then-act rhythm that produces better results on complex workflows.

🧠 Code Mode

Inspired by Code execution with MCP, KubeView ships a sandboxed code runtime for agents to explore the API and run complex workflows.

MCP Bridge – All registered MCP tools are callable from within run_code.
Dynamic TypeScript Definitions – Tool schemas are auto-converted to a typed global.d.ts, preventing hallucinated parameters.
Tool Discovery – tools.search() and tools.list() let agents find capabilities at runtime without loading the full schema.
Sandboxed Execution – Locked-down Node.js vm environment with access only to console and the tools global.

Enable code-only mode:

json

"env": { "MCP_MODE": "code" }

Built-in `code-mode` Prompt

The server includes a code-mode MCP prompt that injects full TypeScript API docs and examples into the agent context. In Cursor, type /kubeview/code-mode in the prompt bar to activate it.

💻 Local Development

bash

# Clone and install
git clone https://github.com/mikhae1/kubeview-mcp.git
cd kubeview-mcp
npm install

# Build and run
npm run build
npm start

# Test
npm test

# Run a tool directly via CLI
npm run command -- kube_list --namespace=default

📄 License

MIT © mikhae1

Install

Configuration

Environment variables

KUBECONFIG

Path to kubeconfig file; defaults to ~/.kube/config if unset.

MCP_TRANSPORT

Transport mode: 'stdio' (default) or 'http'. The published package metadata still targets stdio by default.

MCP_MODE

Server mode: 'all' (default), 'code', or 'tools'. Controls which features are enabled.

MCP_LOG_LEVEL

Logging level: 'error', 'warn', 'info' (default), or 'debug'.

MCP_KUBE_CONTEXT

Kubernetes context name to use. If unset, uses the current context from kubeconfig.

MCP_K8S_SKIP_TLS_VERIFY

Skip TLS certificate verification for Kubernetes API (use 'true' or '1'). Not recommended for production.

MCP_HIDE_SENSITIVE

Enable global sensitive data masking. Set to 'true' or '1' to mask sensitive values in responses.

MCP_TIMEOUT

Default timeout in milliseconds for operations. If unset, uses plugin-specific defaults.

MCP_HTTP_HOST

HTTP bind host when MCP_TRANSPORT=http. Defaults to 127.0.0.1.

MCP_HTTP_PORT

HTTP port when MCP_TRANSPORT=http. Defaults to 3000.

MCP_HTTP_PATH

HTTP endpoint path when MCP_TRANSPORT=http. Defaults to /mcp.

MCP_HTTP_STATELESS

Disable session IDs in HTTP mode. Set to 'true' or '1' for stateless request handling.

MCP_HTTP_JSON_RESPONSE

Prefer JSON responses over SSE in HTTP mode. Set to 'true' or '1' to enable.

MCP_ALLOWED_HOSTS

Comma-separated Host allowlist for HTTP mode. Required when binding to 0.0.0.0 or ::.

MCP_ALLOWED_ORIGINS

Comma-separated Origin allowlist for HTTP mode.

MCP_DISABLE_KUBERNETES_PLUGIN

Disable Kubernetes plugin. Set to 'true' or '1' to disable.

MCP_DISABLE_HELM_PLUGIN

Disable Helm plugin. Set to 'true' or '1' to disable.

MCP_DISABLE_ARGO_PLUGIN

Disable Argo Workflows plugin. Set to 'true' or '1' to disable.

MCP_DISABLE_ARGOCD_PLUGIN

Disable Argo CD plugin. Set to 'true' or '1' to disable.

claude_desktop_config.json

{
  "mcpServers": {
    "kubeview": {
      "command": "npx",
      "args": [
        "-y",
        "kubeview-mcp@1.9.3"
      ],
      "env": {
        "KUBECONFIG": "<YOUR_KUBECONFIG>",
        "MCP_TRANSPORT": "<YOUR_MCP_TRANSPORT>",
        "MCP_MODE": "<YOUR_MCP_MODE>",
        "MCP_LOG_LEVEL": "<YOUR_MCP_LOG_LEVEL>",
        "MCP_KUBE_CONTEXT": "<YOUR_MCP_KUBE_CONTEXT>",
        "MCP_K8S_SKIP_TLS_VERIFY": "<YOUR_MCP_K8S_SKIP_TLS_VERIFY>",
        "MCP_HIDE_SENSITIVE": "<YOUR_MCP_HIDE_SENSITIVE>",
        "MCP_TIMEOUT": "<YOUR_MCP_TIMEOUT>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_PATH": "<YOUR_MCP_HTTP_PATH>",
        "MCP_HTTP_STATELESS": "<YOUR_MCP_HTTP_STATELESS>",
        "MCP_HTTP_JSON_RESPONSE": "<YOUR_MCP_HTTP_JSON_RESPONSE>",
        "MCP_ALLOWED_HOSTS": "<YOUR_MCP_ALLOWED_HOSTS>",
        "MCP_ALLOWED_ORIGINS": "<YOUR_MCP_ALLOWED_ORIGINS>",
        "MCP_DISABLE_KUBERNETES_PLUGIN": "<YOUR_MCP_DISABLE_KUBERNETES_PLUGIN>",
        "MCP_DISABLE_HELM_PLUGIN": "<YOUR_MCP_DISABLE_HELM_PLUGIN>",
        "MCP_DISABLE_ARGO_PLUGIN": "<YOUR_MCP_DISABLE_ARGO_PLUGIN>",
        "MCP_DISABLE_ARGOCD_PLUGIN": "<YOUR_MCP_DISABLE_ARGOCD_PLUGIN>"
      }
    }
  }
}

Topics

KubeView MCP – Kubernetes Model Context Protocol Server

✨ Features

🚀 Quick Start

Prerequisites

Installation

MCP Client Configuration

Environment Variables

Streamable HTTP Mode

🛠️ Tools

Kubernetes

Helm

Argo

Utilities

🧠 Code Mode

Built-in code-mode Prompt

💻 Local Development

📄 License

Install

Configuration

Built-in `code-mode` Prompt