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