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

# 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.):

{
  "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.

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:

"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

# 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