Flux159/mcp-server-kubernetes

MCP Server Kubernetes – AI‑enabled Kubernetes control

What it is – A tiny Node‑style server (run with npx mcp-server-kubernetes) that speaks the Model Context Protocol (MCP). It lets AI‑powered assistants (Claude, Codex, VS Code extensions, Cursor, etc.) issue kubectl‑like commands, Helm actions, port‑forwards, node maintenance, and diagnostics against a local Kubernetes cluster.

Why it matters – By exposing Kubernetes operations through a standard MCP interface, developers can ask an LLM to list pods, apply a manifest, scale a deployment, or troubleshoot a failing pod without writing any CLI code. The server can run in a read‑only mode for safety and optionally emits OpenTelemetry traces for observability.

Quick start

Prerequisites – kubectl, a valid ~/.kube/config, and (optionally) Helm v3. Install the Bun runtime (bun.sh).

Run –

bun install          # install deps
npx mcp-server-kubernetes   # start the server (STDIO or SSE transport)

Connect an AI client – e.g. Claude Desktop, VS Code MCP extensions, or the mcp-chat CLI:
```
npx mcp-chat --server "npx mcp-server-kubernetes"
```
The client will automatically pick up the current kubectl context.

Core capabilities (exposed as MCP tools)

Category	Tools (example)	Description
Resource CRUD	`kubectl_get`, `kubectl_create`, `kubectl_apply`, `kubectl_delete`	List, create, apply YAML, or delete any K8s object.
Inspection	`kubectl_describe`, `kubectl_logs`, `explain_resource`	Detailed description, log tailing, and natural‑language explanations.
Management	`kubectl_scale`, `kubectl_patch`, `kubectl_rollout`, `node_management`	Scale deployments, patch fields, control rollouts, cordon/drain nodes.
Helm	`install_helm_chart`, `upgrade_helm_chart`, `helm_template_apply`, `helm_template_uninstall`	Install/upgrade charts, or render‑then‑apply templates to avoid auth issues.
Port‑forward	`port_forward`, `stop_port_forward`	Expose a pod/service locally.
Diagnostics	`k8s-diagnose`	Guided troubleshooting flow for problematic pods.
Utility	`kubectl_context`, `list_api_resources`, `ping`	Switch contexts, list API groups, health‑check.

All tools can be filtered out in non‑destructive mode (ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true), leaving only read‑only and safe create/update operations.

Observability (optional)

Enable with environment variables:

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
npx mcp-server-kubernetes

Traces every tool call (name, duration, success/failure, K8s context, etc.) and can export to any OTLP‑compatible backend (Jaeger, Grafana Tempo, Datadog, AWS X‑Ray, …).
See docs/OBSERVABILITY.md for sampling, configuration, and deployment examples.

Development & contribution

Build – bun run dev (watch mode), bun run test, bun run build.
Local testing – Use the Model Context Protocol inspector or the bundled mcp-chat CLI.
Contribute – Follow CONTRIBUTING.md; PRs are welcome.
Release workflow – Tag a new vX.Y.Z on GitHub; CI builds and publishes an npm package automatically.

Who might use this

AI‑assisted developers who want their LLMs to manage clusters directly from the editor.
Ops teams building chat‑ops bots that need safe, auditable Kubernetes actions.
Tool makers looking for an MCP‑compatible backend to plug into Claude, Cursor, or custom assistants.

Citation

If you reference the project, use the provided BibTeX entry:

@software{Patel_MCP_Server_Kubernetes_2024,
  author = {Patel, Paras and Sonwalkar, Suyog},
  month = jul,
  title = {{MCP Server Kubernetes}},
  url = {https://github.com/Flux159/mcp-server-kubernetes},
  version = {2.5.0},
  year = {2024}
}