Kubeview MCP Server

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.
• 🔌 MCP 2026-07-28 – Stateless protocol core with discovery, self-describing requests, and header-based routing.

---

🚀 Quick Start

Prerequisites

• Node.js ≥ 20
• 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

Streamable HTTP Mode

KubeView can also run as a standalone Streamable HTTP server for hosted or manually managed deployments. HTTP follows the MCP 2026-07-28 stateless core and creates a fresh MCP server for every request.

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 negotiates either the modern 2026 era or the legacy 2025 era on connection startup.
• HTTP requests do not use initialize, notifications/initialized, or Mcp-Session-Id. Clients can call server/discover, and each request carries the protocol version, client identity, and client capabilities in _meta.
• Modern Streamable HTTP requests include Mcp-Method and, when applicable, Mcp-Name headers for gateway routing and authorization.
• 2025-era clients remain supported through the SDK's stateless legacy fallback on the same HTTP endpoint.
• Application state that must survive multiple HTTP calls should use an explicit tool argument or handle. In particular, plan_step history does not persist across stateless HTTP requests.
• MCP_HTTP_JSON_RESPONSE=true forces JSON-only responses and drops mid-call notifications; leave it disabled for tools that may stream related messages.
• 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

Helm

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

Utilities

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

Testing the MCP 2026-07-28 migration

The migration tests use the SDK v2 client pinned to 2026-07-28 and route requests directly through the server handler, so they do not require an open network port.

# Compile against the split MCP SDK v2 packages
npm run typecheck

# Verify modern discovery, stateless requests, required headers,
# cache hints, header mismatch rejection, and HTTP runtime configuration
npm test -- --runInBand \
  tests/server/StreamableHttpTransport.integration.test.ts \
  tests/server/StreamableHttpRuntime.test.ts \
  tests/server/TransportConfig.test.ts \
  tests/compat/McpSdkCompatibility.test.ts

# Regression suite and production build
npm test
npm run build

For a deployment smoke test, start HTTP mode, connect with an SDK v2 client using versionNegotiation: { mode: { pin: '2026-07-28' } }, then run tools/list and one read-only tool call. Confirm that requests can be distributed across replicas without affinity, contain Mcp-Method/Mcp-Name, and never return Mcp-Session-Id.

---

📄 License

MIT © mikhae1