kubernetes-mcp

A Model Context Protocol server that gives Claude (or any MCP client) full access to a Kubernetes cluster and Helm. Exposes 73 tools covering pods, deployments, services, config, secrets, events, logs, exec, port-forwarding, manifest apply/delete, Helm lifecycle management, nodes, workloads, storage, ingress, batch jobs, rollouts, RBAC, kubeconfig contexts, metrics, HPAs, and CRDs.

Prerequisites

• Node.js 18+
• kubectl configured with a valid kubeconfig
• helm 3.x in PATH

Installation

git clone https://github.com/Stonepusher/kubernetes-mcp.git
cd kubernetes-mcp
npm install
npm run build

Usage with Claude Code

A .mcp.json is included in the repo root. When you open the project directory in Claude Code the kubernetes server is registered automatically. Run /mcp inside Claude Code to confirm it is active, then talk to Claude naturally:

"List all pods in the default namespace" "Scale the echo-server deployment to 3 replicas" "Show me the logs from the nginx pod" "Install bitnami/nginx as my-release in the staging namespace" "What CRDs are installed in this cluster?" "Show me all ClusterRoles and their rule counts"

Manual registration

To register the server globally (outside this directory) add the following to your Claude Code MCP settings:

{
  "mcpServers": {
    "kubernetes": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/kubernetes-mcp/dist/index.js"]
    }
  }
}

Tools

Kubernetes — core resources

Tool	Description
k8s_list_namespaces	List all namespaces
k8s_list_pods	List pods in a namespace (optional label selector)
k8s_get_pod	Get full details of a pod
k8s_list_deployments	List deployments in a namespace
k8s_get_deployment	Get full details of a deployment
k8s_scale_deployment	Scale a deployment to N replicas
k8s_list_services	List services in a namespace
k8s_get_service	Get full details of a service
k8s_list_configmaps	List ConfigMaps in a namespace
k8s_get_configmap	Get a ConfigMap including its data
k8s_list_secrets	List Secrets in a namespace (names/types only)
k8s_get_secret	Get a Secret (values are base64-encoded)
k8s_get_events	Get events in a namespace, optionally filtered by object name

Kubernetes — operations

Tool	Description
k8s_get_pod_logs	Stream or tail logs from a pod container
k8s_exec	Execute a command inside a running pod
k8s_port_forward_start	Start a local port-forward tunnel to a pod
k8s_port_forward_list	List active port-forward sessions
k8s_port_forward_stop	Stop a port-forward session
k8s_apply_manifest	Apply a YAML/JSON manifest (kubectl apply -f -)
k8s_delete_manifest	Delete resources defined in a manifest
k8s_delete_resource	Delete any resource by type, name, and namespace (no manifest needed)

Kubernetes — nodes

Tool	Description
k8s_list_nodes	List all nodes with status, roles, and version info
k8s_get_node	Get full details of a node
k8s_cordon_node	Cordon a node to prevent new pod scheduling
k8s_uncordon_node	Uncordon a node to re-enable pod scheduling
k8s_drain_node	Drain a node by evicting all pods

Kubernetes — workloads

Tool	Description
k8s_list_daemonsets	List DaemonSets in a namespace
k8s_get_daemonset	Get full details of a DaemonSet
k8s_list_statefulsets	List StatefulSets in a namespace
k8s_get_statefulset	Get full details of a StatefulSet

Kubernetes — batch

Tool	Description
k8s_list_jobs	List Jobs in a namespace
k8s_get_job	Get full details of a Job
k8s_list_cronjobs	List CronJobs in a namespace
k8s_get_cronjob	Get full details of a CronJob
k8s_suspend_cronjob	Suspend a CronJob to stop it scheduling new Jobs
k8s_resume_cronjob	Resume a suspended CronJob

Kubernetes — rollouts

Tool	Description
k8s_rollout_restart	Trigger a rolling restart of a Deployment, DaemonSet, or StatefulSet
k8s_rollout_status	Check rollout status and wait for completion
k8s_rollout_undo	Roll back to a previous revision

Kubernetes — storage

Tool	Description
k8s_list_persistent_volumes	List all PersistentVolumes
k8s_get_persistent_volume	Get full details of a PersistentVolume
k8s_list_persistent_volume_claims	List PersistentVolumeClaims in a namespace
k8s_get_persistent_volume_claim	Get full details of a PersistentVolumeClaim
k8s_list_storage_classes	List all StorageClasses
k8s_get_storage_class	Get full details of a StorageClass

Kubernetes — networking

Tool	Description
k8s_list_ingresses	List Ingresses in a namespace
k8s_get_ingress	Get full details of an Ingress

Kubernetes — autoscaling

Tool	Description
k8s_list_hpas	List HorizontalPodAutoscalers in a namespace
k8s_get_hpa	Get full details of a HorizontalPodAutoscaler

Kubernetes — RBAC

Tool	Description
k8s_list_cluster_roles	List all ClusterRoles
k8s_get_cluster_role	Get full details of a ClusterRole
k8s_list_cluster_role_bindings	List all ClusterRoleBindings
k8s_get_cluster_role_binding	Get full details of a ClusterRoleBinding
k8s_list_roles	List Roles in a namespace
k8s_get_role	Get full details of a Role
k8s_list_role_bindings	List RoleBindings in a namespace
k8s_get_role_binding	Get full details of a RoleBinding

Kubernetes — custom resources

Tool	Description
k8s_list_crds	List all CustomResourceDefinitions
k8s_get_crd	Get full details of a CustomResourceDefinition

Kubernetes — contexts & metrics

Tool	Description
k8s_list_contexts	List all kubeconfig contexts and show which is active
k8s_use_context	Switch the active kubeconfig context
k8s_top_nodes	Show CPU/memory usage for all nodes (requires metrics-server)
k8s_top_pods	Show CPU/memory usage for pods in a namespace (requires metrics-server)

Helm

Tool	Description
helm_list	List releases (single namespace or all)
helm_install	Install a chart
helm_upgrade	Upgrade (or install) a release
helm_rollback	Roll back a release to a previous revision
helm_uninstall	Uninstall a release
helm_get_values	Get values for an installed release
helm_history	Get revision history of a release
helm_show_chart_values	Show default values for a chart before installing
helm_repo_add	Add a Helm chart repository
helm_repo_update	Update local Helm repository cache

Development

npm run build      # compile TypeScript → dist/index.js via esbuild
npm run dev        # rebuild on file changes
npm run typecheck  # tsc --noEmit (type-check only, no emit)
npm test           # smoke test — exercises all 73 tools against a live cluster

Smoke test

npm test runs test/smoke-test.mjs, which spawns the MCP server over stdio and exercises all read-only tools against the currently configured cluster. It discovers real resource names dynamically (no hardcoded names) and skips dependent tests gracefully when resources are not found. Write operations (k8s_rollout_restart, k8s_use_context, etc.) are hard-skipped.

Kubernetes MCP Server — Smoke Test
==================================================

── Phase 1: Handshake ──────────────────────────────────────
  [PASS] initialize — serverInfo.name === "kubernetes"

── Phase 2: Tool inventory ─────────────────────────────────
  [PASS] tools/list — count === 73

── Phase 3: Tool assertions ────────────────────────────────
  [PASS] k8s_list_namespaces — returns non-empty array
  [PASS] k8s_list_pods — non-empty array in kube-system
  ...
==================================================
Results  (7.3s elapsed)
  Passed : 55
  Failed : 0
  Skipped: 10

Build notes

@kubernetes/client-node v1.x ships ~54 MB of generated TypeScript types that OOM the TypeScript compiler. The project uses esbuild to bundle to a single CJS file (dist/index.js) without type-checking overhead. Use npm run typecheck separately if you need full type validation.

License

MIT