sandeshghanta/mcp-server-kubernetes-read-only

MCP Server Kubernetes (Python)

Read-only MCP server for Kubernetes cluster inspection using FastMCP and Python kubernetes client.

Copied Heavily inspired from Flux159/mcp-server-kubernetes

Installation

uv pip install -e .

Usage

uv run python -m mcp_server_k8s.server

Example Usage

Get Pods

# Via Claude Code or Claude Desktop
"Show me all pods in default namespace"
"List pods with label app=nginx in production namespace"
"Get pod my-pod in namespace staging"

Get ConfigMaps and Secrets

"List all configmaps in kube-system namespace"
"Show me the secret my-secret in default namespace"
"Get all secrets across all namespaces"

Get Workload Resources

"Show all deployments in production"
"List statefulsets in database namespace"
"Get all daemonsets across all namespaces"
"Show cronjobs in the automation namespace"

Get Networking Resources

"List all services in default namespace"
"Show ingresses in production namespace"
"Get ingress api-gateway in staging"

Get Cluster Resources

"List all namespaces"
"Show all nodes in the cluster"
"Get node worker-node-1"
"Show recent events in kube-system namespace"

Get Autoscaling Resources

"List all HPAs in production namespace"
"Show HPA my-app-hpa details"

Get Istio Resources

"Show all VirtualServices in production namespace"
"List DestinationRules with label app=reviews"
"Get VirtualService bookinfo-vs in default namespace"
"Show all Gateways across all namespaces"
"List ServiceEntries in istio-system"

Get RBAC Resources

"List all roles in default namespace"
"Show rolebindings in kube-system namespace"
"Get role pod-reader in namespace development"
"Show rolebinding developer-binding details"
"List all clusterroles"
"Show clusterrole cluster-admin"
"Get clusterrolebinding system:node"

Describe Resources

"Describe the deployment called my-app"
"Show details of pod my-pod-123 in namespace staging"

View Logs

"Show logs from pod my-pod"
"Get the last 50 lines of logs from deployment nginx"
"Show logs from the app container in pod multi-container-pod"

Troubleshooting

"Diagnose issues with pods matching 'api'"
"/k8s-diagnose keyword=backend namespace=production"

Health Check

"Ping the Kubernetes cluster"
"Check if cluster is accessible"

Tool Reference

Troubleshooting

"Unable to connect to cluster"

Check that:

1. ~/.kube/config exists and is valid
2. Current context is set: kubectl config current-context
3. You have network access to the cluster

"Resource not found"

Verify:

1. Resource name is correct
2. Namespace is correct (default: "default")
3. You have RBAC permissions to view the resource

"Multi-container pod requires container specification"

For pods with multiple containers, specify which container:

"Show logs from container nginx in pod my-pod"

"Istio CRDs not found"

This error occurs when trying to query Istio resources on a cluster without Istio installed.

Check that:

1. Istio is installed: kubectl get crd | grep istio.io
2. You have permissions to view CRDs
3. The Istio version is 1.16+ (uses networking.istio.io/v1 API)

Claude Desktop Configuration

{
  "mcpServers": {
    "kubernetes": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server_k8s.server"]
    }
  }
}

Features

Tools

• kubectl_get - Get/list resources (22 resource types supported)
• kubectl_get_paginated - Paginated resource listing
• kubectl_describe - Detailed resource descriptions
• kubectl_logs - Pod/deployment/job logs
• ping - Health check

Supported Resource Types (22)

Core Workloads (4)

• Pods (pod, pods, po)
• Services (service, services, svc)
• Deployments (deployment, deployments, deploy)
• Jobs (job, jobs)

Additional Workloads (3)

• StatefulSets (statefulset, statefulsets, sts)
• DaemonSets (daemonset, daemonsets, ds)
• CronJobs (cronjob, cronjobs, cj)

Configuration & Storage (2)

• ConfigMaps (configmap, configmaps, cm)
• Secrets (secret, secrets)

Cluster Resources (3)

• Namespaces (namespace, namespaces, ns)
• Nodes (node, nodes, no)
• Events (event, events, ev)

Networking (1)

• Ingresses (ingress, ingresses, ing)

Autoscaling (1)

• HorizontalPodAutoscalers (horizontalpodautoscaler, horizontalpodautoscalers, hpa)

Service Mesh (4)

• VirtualServices (virtualservice, virtualservices, vs)
• DestinationRules (destinationrule, destinationrules, dr)
• Gateways (gateway, gateways, gw)
• ServiceEntries (serviceentry, serviceentries, se)

RBAC & Security (4)

• Roles (role, roles)
• RoleBindings (rolebinding, rolebindings)
• ClusterRoles (clusterrole, clusterroles)
• ClusterRoleBindings (clusterrolebinding, clusterrolebindings)

Prompts

• k8s-diagnose - Systematic troubleshooting flow for Kubernetes pods

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest