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.

---

Available tools

Tool	What it does	Example question
list_pods	List all pods with status, restarts, age, node	"What pods are running in production?"
get_pod_status	Detailed status — phase, conditions, last termination reason	"Why is orders-service unhealthy?"
get_pod_logs	Fetch pod logs; previous=true gets logs from before a crash	"Show me the crash logs for api-gateway"
get_recent_events	Kubernetes events sorted by recency — reveals root cause	"What warning events happened recently?"
get_resource_usage	Live CPU/memory vs requests/limits (requires metrics-server)	"Which pods are near their memory limit?"
get_deployment_status	Rollout status — desired vs ready vs available replicas	"Did the latest deployment roll out successfully?"
scale_deployment	⚠️ Scale a deployment to N replicas	"Scale payments-service to 3 replicas"
restart_pod	⚠️ Delete a pod to trigger recreation	"Restart the crashing orders-service pod"

⚠️ 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

Endpoint	What happens	Simulates
GET /healthy	Returns 200, logs each request	Normal healthy traffic
GET /crash	Throws an error, process exits	CrashLoopBackOff
GET /slow	Sleeps 5 seconds	Latency issues
GET /oom	Allocates memory until killed	OOMKilled event

---

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