k8s-ops-mcp-server

A Model Context Protocol (MCP) server that connects Claude Desktop to any Kubernetes cluster. Ask Claude questions in plain English — it calls your cluster's API, reads the real data, and gives you a diagnosis or performs an action.

"Why is the orders-service pod crashing?"
"Show me recent warning events in the payments namespace."
"Scale the api-gateway deployment to 5 replicas."

Works with any Kubernetes cluster — GKE, EKS, AKS, on-prem, or local Minikube. No code changes needed to switch between them, only a kubectl context switch.

How it works

You (natural language)
        ↓
Claude Desktop  ──── MCP (stdio) ────▶  k8s-ops-mcp-server
                                                ↓
                                     @kubernetes/client-node
                                                ↓
                                     Kubernetes API Server
                                    (GKE / EKS / AKS / Minikube)

Claude decides which tools to call, calls them, and reasons over the results. The MCP server contains no AI — it is a thin, stateless layer over the Kubernetes API. All reasoning happens inside Claude Desktop.

Related MCP server: Kubernetes MCP Server

Available tools

⚠️ Write actions (scale_deployment, restart_pod) default to dryRun=true. Claude will show you what would happen before asking for confirmation to execute.

Prerequisites

• Node.js v18 or later

• kubectl installed, configured, and pointing at your cluster

• Claude Desktop installed

Verify kubectl is connected to your cluster before proceeding:

kubectl get nodes

You should see your cluster nodes listed. If this works, the MCP server will work.

Setup

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/k8s-ops-mcp-server.git
cd k8s-ops-mcp-server

2. Install dependencies and build

npm install
npm run build

3. Verify the server starts

node dist/index.js
# k8s-ops-mcp-server running on stdio

The process hangs waiting for input — that is correct. It is ready for an MCP client to connect. Press Ctrl+C to stop it.

4. Test all tools with MCP Inspector

Before connecting Claude Desktop, verify every tool works using the Inspector — a web UI that acts as a fake MCP client. This is the fastest way to catch issues.

npm run inspector

The terminal prints a URL with a session token:

Open inspector at: http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=abc123...

Open that full URL (including the token) in your browser. Then:

1. Set Command to node

2. Set Arguments to the absolute path to your built server, e.g. /Users/yourname/k8s-ops-mcp-server/dist/index.js

3. Click Connect — all 8 tools appear on the left

4. Try calling list_pods — it should return pods from your cluster

Get the absolute path by running echo "$(pwd)/dist/index.js" in the project directory.

5. Configure Claude Desktop

Open the Claude Desktop config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the mcpServers section (keep any existing content in the file):

{
  "mcpServers": {
    "k8s-ops": {
      "command": "node",
      "args": ["/absolute/path/to/k8s-ops-mcp-server/dist/index.js"]
    }
  }
}

Replace the path with the actual absolute path on your machine (the output of echo "$(pwd)/dist/index.js").

Quit Claude Desktop completely with Cmd+Q and reopen it. Click the "+" icon → Connectors — you should see k8s-ops listed and enabled with all 8 tools.

6. Start diagnosing

Open a new chat and ask:

"List all pods and highlight any that are unhealthy."
"Why is the orders-service pod restarting?"
"Show me warning events from the last few minutes."
"What is the CPU and memory usage across all pods in the default namespace?"

Switching between clusters

The server uses kubectl's active context. To point it at a different cluster:

# List available contexts
kubectl config get-contexts

# Switch context
kubectl config use-context YOUR_CONTEXT_NAME

Then restart Claude Desktop (or just start a new conversation — the server process reloads the config). No code changes, no config file edits.

Example: connecting to GKE

gcloud container clusters get-credentials YOUR_CLUSTER --zone us-central1-a
kubectl config use-context gke_your-project_us-central1-a_your-cluster

# Restart Claude Desktop — it now talks to GKE

Local testing with Minikube

Skip this section if you already have a real cluster to connect to. This is only for trying the server locally without a cloud cluster.

Minikube runs a single-node Kubernetes cluster on your laptop inside Docker. It is useful for testing the MCP tools against a real (though local) cluster, and for triggering deliberate failures to practice diagnosing them.

Start Minikube

# Install Minikube if needed: https://minikube.sigs.k8s.io/docs/start/
minikube start

# Enable metrics-server (required for get_resource_usage)
minikube addons enable metrics-server

Verify it is running:

kubectl get nodes
# NAME       STATUS   ROLES           AGE
# minikube   Ready    control-plane   1m

Deploy the test app

The test-app/ directory contains a small Node.js app designed to simulate real failure modes — crashes, OOM kills, and latency spikes.

Step 1 — Point Docker at Minikube's internal engine

This lets Kubernetes find the image without a registry. Must be run in every new terminal session.

eval $(minikube docker-env)

Step 2 — Build the image

docker build -t test-app:latest ./test-app

Step 3 — Deploy

kubectl apply -f test-app/k8s-manifests/

# Watch pods start
kubectl get pods -w
# NAME                        READY   STATUS    RESTARTS   AGE
# test-app-584b76c4fc-bfwgb   1/1     Running   0          15s
# test-app-584b76c4fc-svqbk   1/1     Running   0          15s

Trigger failures to test your MCP tools

# Get the test app URL
URL=$(minikube service test-app --url)

# Trigger a crash — causes CrashLoopBackOff after the liveness probe fails
curl $URL/crash
curl $URL/crash

# Trigger OOMKill — pod gets killed for exceeding the 64Mi memory limit
curl $URL/oom

Then ask Claude Desktop:

"The test-app pod keeps restarting. What's wrong with it?"

Claude will call list_pods → get_pod_status → get_pod_logs (with previous=true) → get_recent_events automatically and return a real diagnosis.

Test app endpoints

Project structure

k8s-ops-mcp-server/
├── src/
│   ├── index.ts                      # MCP server entry point
│   ├── k8s/
│   │   ├── client.ts                 # Kubernetes client (loadFromDefault)
│   │   ├── podOperations.ts          # listPods, getPodStatus, getPodLogs, restartPod
│   │   ├── deploymentOperations.ts   # getDeploymentStatus, scaleDeployment
│   │   ├── eventOperations.ts        # getRecentEvents
│   │   └── metricsOperations.ts      # getResourceUsage
│   ├── tools/
│   │   ├── definitions.ts            # MCP tool schemas and descriptions
│   │   └── handlers.ts               # Routes tool calls to k8s functions
│   └── utils/
│       └── formatter.ts              # Cleans up raw k8s API responses
│
├── test-app/                         # Deliberately flaky app for local testing
│   ├── app.js
│   ├── Dockerfile
│   └── k8s-manifests/
│       ├── deployment.yaml           # 2 replicas, 64Mi memory limit, liveness probe
│       └── service.yaml
│
├── package.json
└── tsconfig.json

Troubleshooting

kubectl get nodes fails Your kubeconfig is not set up. Follow your cluster provider's instructions to configure it (e.g. gcloud container clusters get-credentials ... for GKE).

MCP Inspector connection error Use the full URL printed in the terminal — it includes a required session token (?MCP_PROXY_AUTH_TOKEN=...). Opening localhost:5173 without the token fails.

get_pod_logs returns an error Use the exact pod name from list_pods output (e.g. orders-service-7d9f8b-x2k1p), not the deployment name. After a crash, set previous=true to get logs from before the restart.

get_resource_usage fails Metrics server is not installed or not yet ready. On Minikube: minikube addons enable metrics-server. On GKE/EKS it is usually pre-installed. Wait ~60 seconds after enabling it before querying.

Tools disappear from Claude Desktop The MCP server process crashed. Confirm the path in claude_desktop_config.json is the correct absolute path, then restart Claude Desktop.

Minikube: ErrImageNeverPull The image was built in your laptop's Docker, not Minikube's. Run eval $(minikube docker-env) in the same terminal, rebuild the image, then restart the deployment:

eval $(minikube docker-env)
docker build -t test-app:latest ./test-app
kubectl rollout restart deployment/test-app

Security

This server is intended for personal or local use. Write actions execute immediately once confirmed — there is no authentication or authorization layer.

• Do not expose this server over a network

• Do not use in a shared or multi-user environment without adding an authorization layer

• All write actions (scale_deployment, restart_pod) are logged to stderr with a timestamp for local audit purposes

• Be careful when connected to a production cluster — Claude will confirm before write actions, but always review before approving