Kubernetes

You manage Kubernetes clusters directly from a dedicated MCP server that integrates with your MCP clients. You can connect to a cluster, run kubectl-like operations, manage Helm charts, perform safe pod and node maintenance, and troubleshoot with guided prompts—all through a single, consistent MCP interface.

How to use

You connect to your Kubernetes cluster from an MCP client using a local, standard MCP server that runs as a process on your machine. The server exposes a unified kubectl API surface for common cluster tasks, supports Helm operations, and includes safety features like a non-destructive mode to prevent accidental deletions. Start by configuring a client (Claude Desktop, VS Code, Cursor, or mcp-chat) to point at the MCP server, then perform operations such as list resources, describe pods, apply manifests, or manage deployments with familiar commands.

How to install

# Prerequisites
- Node.js and npm or an appropriate runtime for the MCP server
- bun (required for local development scripts)
- A Kubernetes cluster and a valid kubeconfig
- kubectl installed and in your PATH
- Helm v3 installed (optional if you plan to use Helm operations)

# Install from source (example development flow)
git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

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

# Run unit tests
bun run test

# Build for local testing
bun run build

# Local testing with Claude Desktop (example)
# Add this MCP server in Claude Desktop with the following config:
# {
#   "mcpServers": {
#     "mcp-server-kubernetes": {
#       "command": "node",
#       "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
#     }
#   }
# }

Configuration and usage notes

The MCP server is designed to load kubeconfig data from multiple sources with a clear priority. By default, it uses the kubeconfig file located at ~/.kube/config. You can supply alternative authentication methods, environment variables, or custom kubeconfig paths to fit your environment.

To integrate with clients, you typically provide a simple configuration that tells the client how to start the MCP server. Examples show starting the server via npx so that you can keep using standard MCP client tools without installing additional runtimes.

Advanced usage and safety features

Use the non-destructive mode to lock the server to read-only or create/update-only operations. This helps protect clusters in shared environments.

The server includes a range of tools for Kubernetes management, including resource querying, creation, updates, rollouts, port forwarding, and Helm chart operations. It also provides a guided troubleshooting prompt for diagnosing pod issues.

Seeded prompts and tools aim to keep you in control while providing actionable guidance. You can verify connectivity to your cluster by performing a simple check such as listing pods in the current context.

Troubleshooting and diagnostics

If you encounter connectivity or permission issues, verify that your kubeconfig context is correct and that kubectl can access the cluster from your shell. Use the provided prompts to guide you through collecting pod evidence and remediation steps.

Environment and security notes

Sensitive data in commands and responses is masked where possible to protect secrets. If you enable non-destructive mode, ensure you understand which operations are allowed and which are blocked.

Examples of common tasks

# List pods in the default namespace
kubectl get pods

# Describe a specific pod
kubectl describe pod my-pod-1

# Apply a manifest
kubectl apply -f my-deployment.yaml

# Get logs from a pod
kubectl logs my-pod-1

# Scale a deployment
kubectl scale deployment my-app --replicas=3

# Port forward to a pod
kubectl port-forward pod/my-pod-1 8080:80

Available tools

kubectl_get

Get or list resources such as pods, services, deployments. Supports namespace and resource type filtering.

kubectl_describe

Describe a specific resource to view details and events.

kubectl_logs

Fetch logs from a pod or container for debugging.

kubectl_apply

Apply YAML manifests to create or update resources.

kubectl_create

Create resources from manifest data.

kubectl_delete

Delete resources with optional force and grace period.

kubectl_context

Switch or manage kubectl contexts.

explain_resource

Explain the shape and fields of a Kubernetes resource.

list_api_resources

List available API resources in the cluster.

kubectl_scale

Scale deployments or other scalable resources.

kubectl_patch

Patch fields on a resource without full replacement.

kubectl_rollout

Manage deployment rollouts and status.

kubectl_generic

Execute any kubectl command through the MCP interface.

ping

Verify that the MCP server can reach the Kubernetes API.

port_forward

Set up port forwarding to a pod or service.

install_helm_chart

Install a Helm chart into the cluster.

upgrade_helm_chart

Upgrade an existing Helm release.

helm_template_apply

Template-based Helm installation by applying generated manifests.

helm_template_uninstall

Template-based uninstallation by removing generated manifests.

cleanup_pods

Clean up problematic pods in specified states.

node_management

Cordone, drain, and uncordon nodes for maintenance and scaling.

k8s-diagnose

Guided prompt for Kubernetes pod troubleshooting.