Kubernetes MCP Server

This page documents the maintained community server Flux159/mcp-server-kubernetes. It is published on npm as mcp-server-kubernetes and on Docker Hub as mcp/kubernetes.

The server connects to a Kubernetes cluster through kubectl and exposes cluster operations as MCP tools.

What it Does

• Cluster inspection: Get and describe nodes, namespaces, pods, deployments, services, and other resources
• Pod operations: Fetch logs, execute commands in pods, and clean up pods in failed states
• Deployment operations: Create, apply, patch, scale, delete, and manage rollouts
• Helm operations: Install, upgrade, and uninstall charts
• Networking: Forward ports to pods and services
• Node management: Cordon, drain, and uncordon nodes
• Safety modes: Non-destructive mode and secrets masking

Installation

Prerequisites: kubectl installed and in your PATH, a valid kubeconfig with contexts configured, and Helm v3 if you plan to use Helm tools.

# Using npx
npx -y mcp-server-kubernetes

# Using Docker
docker run -i --rm -v ~/.kube:/root/.kube mcp/kubernetes

By default the server loads kubeconfig from ~/.kube/config.

Configuration

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "mcp-server-kubernetes"]
    }
  }
}

To run without destructive operations, set the documented environment variable:

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["-y", "mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

Available Tools

The full tool list is in the upstream README.

Common Workflows

Investigating a Pod Crash Loop

1. Use kubectl_get to list pods in the affected namespace
2. Use kubectl_describe to check recent events and container status
3. Use kubectl_logs to fetch logs from the crashing container
4. Use kubectl_get with resourceType set to events to check for broader issues
5. Ask "What is causing this pod to crash loop based on the logs and events?"

Scaling for Traffic

1. Use kubectl_get to find the target deployment and check its status
2. Use kubectl_scale to set the desired replica count
3. Use kubectl_get to monitor the new pods
4. Use kubectl_rollout to check rollout status
5. Verify service endpoints with kubectl_get

Cluster Health Check

1. Use kubectl_get to list nodes and their status
2. Use kubectl_get to review events
3. Use kubectl_get to check pod distribution across namespaces
4. Use kubectl_describe on any pending or failing pods
5. Generate a cluster health summary

Example Prompts

• "Show me all pods in the default namespace"
• "What deployments are failing in production?"
• "Get logs from the api-server pod"
• "Scale the web deployment to 5 replicas"
• "List all services with external IPs"
• "Check events for the last hour across all namespaces"

Troubleshooting

Security Notes

• Run with ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true for production clusters
• Use read-only service accounts and limit RBAC permissions to required resources
• The server masks sensitive data in kubectl get secrets output, but logs are not masked
• Never expose a kubeconfig with admin credentials to AI assistants

Sources

• https://github.com/Flux159/mcp-server-kubernetes
• https://hub.docker.com/r/mcp/kubernetes
• https://www.npmjs.com/package/mcp-server-kubernetes