MCP Server Kubernetes

How to use

You can use this MCP server with any MCP client that supports the Model Context Protocol. Start by ensuring your local environment can reach your Kubernetes cluster via kubectl. You will interact with the MCP server to perform Kubernetes actions through familiar kubectl-like commands, Helm operations, and resource management features. The server automatically uses your kubeconfig and context to operate against the cluster.

How to install

Prerequisites to run the MCP server locally include a working Node or Bun environment and access to a Kubernetes cluster.

bash
# 1) Clone the repository
git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes

# 2) Install dependencies using Bun (bun install) or switch to your preferred package manager
bun install

# 3) Run in development mode (watches for file changes)
bun run dev

# 4) Optional: run unit tests
bun run test

# 5) Build for production if needed
bun run build

# 6) Local testing with Inspector (example)
npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link

# 7) Local testing with Claude Desktop (example)
# Place this in your Claude Desktop mcpServers config as shown in the Claude integration section
"} ,{

Configuration and usage notes

OpenTelemetry observability is optional and can be enabled through environment variables. When enabled, the server will emit traces to OTLP backends such as Jaeger, Grafana Tempo, or Grafana Cloud.

Observability (optional)

Enable observability by setting environment variables and then starting the server. You can route traces to your preferred OTLP backend.

bash
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

npx mcp-server-kubernetes

# Example: view traces at your OTLP backend (e.g., Jaeger UI) if you run Jaeger locally.

Non-destructive mode

You can run the server in non-destructive mode to disable all destructive operations. This is useful for read-only workflows or safer exploration of cluster state.

bash
ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

# Or configure a Claude Desktop profile to enable non-destructive mode by setting the environment variable in the config
{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

Prompts and prompts usage

The MCP Kubernetes server includes prompts to guide you through Kubernetes troubleshooting and diagnostics. Use the provided prompts to investigate pods, namespaces, and cluster state in a structured workflow.

Architecture overview

The server provides a unified API for Kubernetes operations, routing requests to appropriate handlers and interacting with the Kubernetes API. A typical flow involves a client request, transport, server routing, tool filtering, and execution against Kubernetes resources or Helm charts.

Local development workflow

Development steps let you iterate quickly while contributing to the MCP server.

Contributing

ConTRIBUTING guidelines outline how to contribute changes, run tests, and review code quality. Follow the project’s contribution process to propose improvements or fixes.

Advanced usage notes

Advanced options include using non-destructive mode, running Helm operations, and performing port forwarding. You can also perform lifecycle operations on deployments, pods, and other Kubernetes resources through a consistent MCP API.

API tools and capabilities

The MCP Kubernetes server exposes a rich set of tool functions for Kubernetes and Helm operations. You can list resources, describe resources, create or apply manifests, patch fields, manage rollouts, scale deployments, perform port forwarding, run Helm charts, and execute arbitrary kubectl commands via a unified interface.

Example commands and configurations

To integrate with Claude Desktop or other MCP clients, you typically reference the MCP server as an npm-based command. A common approach is to run the MCP server with npx and point clients to that server.

kubectl_get

Retrieve Kubernetes resources or lists, matching kubectl's get behavior via MCP.

kubectl_describe

Describe a resource to show detailed information about its state.

kubectl_apply

Apply YAML manifests to create or update resources.

kubectl_create

Create new Kubernetes resources from definitions.

kubectl_delete

Delete Kubernetes resources.

kubectl_logs

Fetch logs from containers in pods.

kubectl_context

Manage and switch Kubernetes contexts.

kubectl_patch

Patch fields of a resource.

kubectl_rollout

Manage deployment rollouts.

kubectl_scale

Scale deployments or other scalable resources.

port_forward

Forward ports from pods or services to local machine.

install_helm_chart

Install a Helm chart into the cluster.

upgrade_helm_chart

Upgrade an existing Helm release.

helm_template_apply

Render Helm templates and apply them in a non-authenticated way.

helm_template_uninstall

Render Helm templates for uninstall without authentication issues.

cleanup_pods

Remove problematic pods in specific states to recover clusters.

node_management

Cordone, drain, and uncordon nodes for maintenance.

k8s-diagnose

Systematic Kubernetes troubleshooting prompt for pods.

ping

Verify connectivity to the Kubernetes API.